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Trumpcard Professional Gate Array 
achieves SCSI transfer rates up to 1.9 
Mbytes/sec as measured by DPERF2. 




Memory Controller Gate Array 
includes memory arbitration and smart 
refresh logic to guarantee lowest 
possible power consumption. ..less 
than 0.9 amps with 8 megs! 



Fast RAM expansion in 
0,2, 4, 6, or 8 Mbyte 
increments using easy 
to install SIMM 
memory modules. 



Multi layer PC board for noise-free 
operation. 




High quality RGB output for your Amiga 

These images are completely unretouched photos taken from a sLock 1084s RGB monitor. 

They are pure RGB, not smeary composite. No other graphics expansion device offers so 
much performance and costs so little! And all the software to run U is free. Even upgrades! 
There's not enough room to cover all the great features of this system, so here are just a few. 



System Features: 

• Paint, render. CVt ip S/W 

• 18 2-1 bit "pure" modes 

• 256/512 color register modes 

• RGB pass through 

• Screen overlay underlav 

• Screens pull up clown & 
go (rent/back 

• View With any IFF Viewer 

• Animate via APJIM or 
Pa^je Flipping 

• Works with DtgiVjew™ 

• Completely bHucr-Lompatihle 
•NTSC encoder compatible 

• S VMS encoder compatible 

• PAL & NTSC compatible 

• Uses only RGB port 

• FCC Class B. IX Listed 

• Works w'std Arnica monitors 

• Dt>t'r> not n.sc Arnica power 



Paint Features: 

• Custom brushes use blitter 

• RGB. HSV. HSL, CMY palt-tte 

• RGB and HSV spreads 

• Extensive ARexx™ support 

• 10 Color Cycle'Glow ranges 

• Range pom;, reverse, stop 

• Smooth zoom, rotate or scale 

• Area. Edge, outline fill overfill 

• Dithered 24 bit All miximi 

• Anti-alias with any tool or brush 

• Loads, shows GIF" exactly 

• "C" source code available free 

• Upgrade from BBS 24 hrs day 

• Color or 256 greys painting 

• 256 color stencils 

• Ma lie color anti-alias cycle draw 
■ Prints via printer device 

• Auto enhance std IFF palettes 

• Writes IFF24. GIF™ HAM-E 



Image Compatibility: 

• 24 bit EFF. 24 bit IFF with C LI_T 
chunks: 2 to 256 color stan- 
dard IFF. half bright, HAM. 
DKBaiidQRT trace: RGBS 
andRGBN:Targa™;GlF"* ; 
Dynamic II iRes,™ SHAM. 
ARZO. ARZ1. AHAM. 16 bit 
ScanLab"*: L'PBS brushes; 
AlloMie 12 different HAM-E 
format image 11 le types. 

• Images may be scaled and 
converted to 24 bit IFF files. 

• Image processing software 
supplied provides edge en- 
hancement, blur, various con* 
volutions, and much more. 
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What are you missing 
if you don't have the AG's TECH Premiere Issue? 



PREMIERE ISSUE 



Advanced Dissassembling: Magic Macros with Resource 

AmigaDOS, EDIT, and Recursive Programming Techniques 

Building the VidCeil 256 Grayscale Digitizer 

An Introduction to Interprocess Communication with ARexx 

An introduction to the ilbm. library 

Creating a Database in C, Using dBC III 

Using Intuition's Proportional Gadgets from FORTRAN 77 

FastBoot: A Super BootBlock 

AmigaDOS for Programmers 

Adpating Mattel's Power Glove to the Amiga 

Dorft ft/Jiss Out! 

AC'S TECH Premiere Issue is in short supply, so order your copy today! 



Call 1-800-345-3360 from anywhere in the US or Canada. 

(credit cards only, please) 
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Half length card allows 
space for "hard card" 
configurations. 



Dual 50 pin SCSI connectors 
for flawless SCSI data transfers 
even at top speeds. 

Output only parallel port connects to 
printer allowing simultaneous operation 
of printer and any audio or video digitizer 
connected to Amiga's parallel port. 



SCSI ID jumpers for use in exclusive 
IVS SCSI-SHARE SCSI networking 
environments. 



Grand Slam includes card, 

disk mounting brackets, cables, 

TCUTILS 2.0 hard drive formatting/ 

network configuration utility, 

comprehensive memory test software and 

parallel port configuration/patcher utility software. 

Grand Slam 500 is available for Amiga 500 owners. 

Naturally, Trumpcard, Trumpcard 500, Trumpcard Pro and 
Trumpcard 500 Pro owners can upgrade. Call IVS for details. 

llUlll^VHiu *sw L a A mi Sa is a Trademark or Commodore Business Machines 

Grand Slam List Price $349.95 



7245 Garden Grove Blvd., Suite E • Garden Grove, CA 92641 
Voice: (714) 890-7040 • Fax: (714) 898-0858 
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printf ("Hello") ; 



print "Hello 



rr 



JSR printMsg 



say "Hello 



// 



writeln ("Hello") 



Whatever language you speak, AC's TECH 

provides a platform for both gaining insight 

and sharing information on its most 

innovative implementation for the Amiga. 

Why not see if your latest programming 

endeavor can help a fellow Amiga user 

expand upon his or her vocabulary? To be 

considered for publication in AC's TECH, 

submit your technically oriented article 

(both hard copy & disk) to: 

AG's TECH Submissions 

PIM Publications, Inc. 
One Currant Place 
Fall River, MA 02722 
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Amiga in the Spotlight 

The Amiga and the Video Toaster have been stirring up a 
lot of interest lately in the MS-DOS and Macintosh communi- 
ties! It appears that NewTek and the Video Toaster attracted 
big crowds at a recent MacWorld Expo. Also, there have been 
several small articles m various MS-DOS trade publications, 
including a mention in John Dvorak's column in PC Magazine. 
This is fantastic, but there's a small quirk. These people, who 
are awed by the Amiga's capabilities, really don't recognize the 
Amiga itself. Instead, they refer to the Amiga /Video Toaster 
combination as a video computer that comes with an Amiga, 
or a great video peripheral that's soon to be controlled from an 
IBM PC. Crazy, right? 

Right! But that's OK. Let theMS-DOS community think 
whatever it wants. The fact is that it is being mesmerized by 
the only hardware platform that could support the Video 
Toaster or anything like it — the Amiga! Now this is where it 
gets good. Some of these big cash MS-DOS software vendors 
are going to want part of the Video Toaster action (that's 
market share to the pinstripers). So they get their best, hot-shot 
programmers, give them an Amiga and a stack of books and 
technical notes, and let them go. This is where Joe-MS-DOS- 
hot-shot programmer discovers the Amiga's powerful operat- 
ing system. He shows the suits some snazzy Amiga program- 
ming, the suits see dollar signs, and the company dumps a lot 
of money into Amiga software development. 

This is good for everyone involved, because it creates a 
larger market. The larger the market, the more potential 
customers to buy your software. The more software you sell, 
the more development you can invest in to create new prod- 
ucts. Your new products create a larger market, and so on. It's 
a rolling snowball, and it's a win-win situation. 

Discoveries 

Everyone's heard of CDTV. This has got to be one of the 
most awaited Amiga products of all time (after the Toaster, of 
course.) Commodore, with Nolan Busnell, is nursing this baby 
to make sure nothing goes wrong. It's sure to be a best seller. 



Many Amiga programmers and developers don't realize 
the incredible opportunity that CDTV provides. With the 
CDTV will come an enormous customer base just looking to 
buy software for their new high-tech home appliance. Educa- 
tional software is sure to be a big seller, along with entertain- 
ment and home resources software. The market is wide open. 

Plus, there are several developmental advantages to 
CDTV. First, the user can't illegally duplicate and distribute 
the disc. No piracy. Also, the duplication of the discs is very 
cost-effective. There have been rumors of some duplication 
houses charging a $500-$600 mastering fee, and $.75/piece for 
duplication. 

The disadvantages are few. There are very strict style 
guidelines for producing CDTV software, including the fact 
that windows are not allowed. This simple fact means that 
most software cannot be just ported, but will require a little 
redesign. Kudos to Commodore for finally putting some style 
control on the Amiga software. It's definitely a necessary evil. 

For you technies who want to get a jump on CDTV 
technology, Commodore reports that CDTV's will be for sale at 
The World of Commodore, New York (April 5-7). Get 'em while 
their hot! 

The Amiga's future looks bright. Be a part of it. For more 
information on Commodore's developmental programs, contact: 

Commodore Business Machines 
CATS — Developer Programs 
1200 Wilson Drive 
West Chester, PA 19380 



Sincerely, 

Ernest P. Viveiros, Jr. 
Editor 
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Dear AC's TECH, 

Congratulations on your first issue of AC's TECH for 
the Commodore Amiga! I loved it! My favorite articles 
were the 'ilbm.library' and 'AmigaDOS for Program- 
mers.' I originally wrote a file-identification program 
called What Is in Modula-2 and after getting SAS/C I 
was excited about converting it to C. The 'Introduction 
to the ilbm.library' article has been an extreme help in 
converting my code, and now I am going to make full 
use of this shared library. The 'AmigaDOS for Program- 
mers' story was a nice introduction to file locks. Thanks 
for the help! 

I liked the VidCell digitizer hardware project article. 
Though I am completely hardware-illiterate and did not 
understand it all, I liked the reading anyway. Perhaps in 
the future you could include an article that is a brief 
explanation of hardware concepts so that this sort of 
article would be easier to follow, and maybe even give 
me the courage to try on my own. 

What I liked best about the magazine was the on-disk 
examples. Having this code was a great way to learn and 
useful as a springboard for my own programs. 

In response to the To 2.0 or not to 2.0' quandary, I 
suggest this: why not develop two versions? Each piece 
of software could easily be developed in 1.3 find then 
include an enhanced version for 2.0. Both versions could 
be included in the same box. This would be like the 
68000 and 68020/030 versions now available for some 
programs. 

I love the magazine, I love the info, and I love the 
style! I can't wait for the next issue, keep up the good 
work. 

Ryan Sheftel 
Rosemont, PA 



Dear Ryan, 

Thank you for writing! Your enthusiasm typifies the 
average AC's TECH reader. We 'techies' continue to be 
excited about the Amiga! We aren't the type to jump on the 
mos t-popula r-computer-of- thc-yea r bandwagon — bi 1 1 we 've 
stuck loyally with the Amiga, even through the tough times. 
In a sense when the Amiga makes the big win, you won't be 
sorry! 

In regards to your idea about packaging 1 .3 and 2.0 
versions together. I think this is a good idea. ..as a short-term 
solution. Everyone's favorite workhorse program has to xvork 



under AmigaDOS release 2 before we even consider the 
system software upgrade. However, the long-haul plan is not 
only to update the 13 programs to run (bug-free, of course) 
under AmigaDOS release 2, but to redesign the application to 
take advantage of the new features that release 2 brings the 
programmer. Let's show what the Amiga can do! 

—EPVjr 



Dear AC's TECH, 

I have recently purchased the Premiere issue of AC's 
TECH, and was quite surprised with its content. By its 
description, I had assumed it would be a technical guide 
to using and controlling the Amiga. I didn't expect about 
30-50% of the magazine to be about programming and 
the rest on 'how the Amiga does this, that, and the other 
thing', but alas it was 90% programming. I did read and 
enjoy it a great deal, even though I am NOT a program- 
mer. 

I have read and enjoyed Amazing Computing and 
will continue to do so in the future, but I would really 
like to see some articles about board specifications, the 
exact boot-strap process, is BUSTER a 32-bit chip?, how 
does the auto-configure process work?, etc... 

I know I will be creating my application software in 
the near future, and your magazine will help me along. 

Greg Bastow 

Surrey, BC Canada 



Do you have a comment about AC's TECH or anything 
else in or around Amiga programming/development? 
Redirect your voice to your pen & paper port, then mail 

your message to: 

AC's TECH MessagePort 

P.O. Box 869 

Fall River, MA 02722-0869 

If we publish your letter, you will receive a certificate 
good for five free public domain disks from PiM Publi- 
cations, Inc. 

(All letters become the property of PiM Publications, Inc. 
The AC's TECH editors reserve the right to edit all 
letters for length and clarity.) 
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The Complete Amazing Computing library 

which now includes Volume 5 

is available at incredible savings of 50% off! 

♦ Volume 1 is now available for just $19.95*! ♦ 

(A $45.00 cover price value, the first year of AC includes 9 info-packed issues.) 

♦ Volumes 2, 3, 4, & 5 are now priced at just $29.95* each! ♦ 

(Volumes 2,3, & 4 include 1 2 issues each, and are cover priced at $60.00 per volume set.) 



Subscribers can purchase freely redistributable disks** at bulk rate discount prices! 
This unbeatable offer includes all Fred Fish, AMICUS, and AC disks 

(see [heFall/Winter'90 AC'S Guide for a complete index of all current freely redistributable disks). 



Pricing for subscribers is as follows: 

♦ 1 to 9 disks: $6.00 each 

♦ 10 to 49 disks: $5.00 each 

♦ 50 to 99 disks: $4.00 each 

♦ 100 disks or more: $3.00 each 

(Disks are priced at $7.00 each and are not discounted for non-subscribers) 

To get FAST SERVICE on volume set orders, freely redistributable disks, 
or single back issues, use your Visa or MasterCard 

call 1-800-345-3360 

Or, just fill out the order form on page 98. 

' Postage 4 handling for each volume is $4.00 in the U.S.. $7,50 (or surface in Canada and Mexico, and $1 0.00 for all other foreign surface. 

" AC warranties all disks for 90 days. No additional charge for postage and handling on disk orders. AC issues Mr. Fred Fish a royalty on all disk sales to encourage 

the leading Amiga program anthologist to continue his outstanding work. 



CAD APPLICATION DESIGN 

PART I— WORLD AND VIEW TRANSFORMS 



by FOREST W. ARNOLD 



INTRODUCTION 

With modem computer-aided design (CAD) systems, 
models of real or imagined objects can be quickly and easily 
created, displayed on a monitor, or plotted on a plotter or 
printer. Model objects can be readily changed, and the effect of 
the modifications can be instantly seen and evaluated. 

Objects can be moved around, made bigger or smaller, 
and turned around and upside down. We can create and 
experiment with models of objects smaller than atoms or as 
large as the universe - all on a computer monitor. We can 
'zoom in' on part of an image to examine small details, then 
'zoom out' to see the image in its entirety. 

Since we can create and manipulate complex models with 
CAD systems, we might expect CAD software to be complex. 
However, no matter how complex the model or the CAD 
system, all CAD systems are butt around a surprisingly small 
number of relatively simple software procedures. 

This is the first of two articles which will explore the basic 
procedures used in vector-based two-dimensional CAD 
systems. In this article, we'll take a look at the mathematics 
which makes CAD systems possible. We'll then develop a 
library of useful, general-purpose transformation procedures 
for manipulating two-dimensional graphical objects. Also, 
we'll see how drawings are displayed in a window or plotted 



on a plotter at any scale or rotation angle. In a later article, 
we'll take a look at direct manipulation techniques used in 
CAD systems, and combine these techniques with our trans- 
form procedures to create the basic part of a two-dimensional 
drawing program. 

CARTESIAN COORDINATES AND VECTORS 

Let's start out by seeing how CAD systems model the 
world and the geometric objects in it. One of the simplest ways 
to represent geometric objects is with Cartesian coordinates. A 
two-dimensional Cartesian coordinate system is formed by 
imagining a vertical line and a horizontal line in a plane which 
cross each other, then measuring distances along the lines from 
the place where the two lines cross. The vertical line is called 
the y axis and the horizontal line is called the x axis. Distances 
along the x axis are called x coordinates and distances along ; 
the y axis are called y coordinates. The units for measuring 
distances along the axes can be inches, meters, light-years, or 
whatever unit of measure is appropriate for the objects to be 
described. 

Any point can be located relative to the two coordinate 
axes by specifying its x coordinate and its y coordinate. The 
usual way coordinates are written is as an ordered pair of 



8 



AC'S TECH 




MATHEMATICS 8c TECHNIQUES FOR 
DESIGNING AND PROGRAMMING 
CAD SOFTWARE FOR THE AMIGA™ 



numbers inside parentheses, with the x coordinate written 
first, followed by the y coordinate. The coordinates where the 
axes cross each other is (0,0). This point is called the origin of 
the coordinate system. X coordinates to the right of the origin 
are positive, and are negative on the left side of the origin. 
Likewise, y coordinates above the origin are positive, and are 
negative below the origin. So (1,0) represents a point on the x 
axis which is 1 unit to the right of the origin, and (0,-1) 
represents a point on the y axis which is 1 unit below the 
origin. 

After a coordinate system has been set up and an object is 
drawn in the coordinate system, any point on the object can be 
described in terms of its Cartesian coordinates. Figure one (see 
page 10) shows how a rectangle can be drawn in a Cartesian 
coordinate system. The rectangle in figure one is described by 
specifying the location of the corners of the rectangle in 
Cartesian coordinates. The sides of the rectangle are line 
segments which connect the corners. In a program, one of the 
simplest data structures for storing and using the Cartesian 
coordinates defining a set of connected points is an array. 

The (x,y) pairs are stored in contiguous array locations. 
Each point is implicitly connected to the next point in the array 
by a line segment. Any point in the figure can be chosen as the 




starting point. For the rectangle in figure one, an array which 
can hold 10 coordinates is needed (for closed figures, the last 
coordinate pair and the first coordinate pair are usually the 
same). If the upper, left corner is chosen as the starting point, 
the array of coordinates defining the rectangle is: 

Index: 123456789 

Coordinate: xyxyxyxyxy 
Value: -4 2 4 2 4-2-4-2-4 2 

Coordinate pairs representing single points are also called 
vectors. Vectors are very similar to Cartesian coordinates. Both 
can be represented using the same notation, (x,y), and both 
specify distances and directions. The difference between 
vectors and coordinates is that coordinates always define 
directed distances from the origin along the coordinate axes, 
and vectors define directed distances from ANY point, which 
is not necessarily the origin. 

The coordinate system used to describe geometric objects 
is called a WORLD coordinate system. The coordinate system 
used to draw the images of the objects is called a VIEW 
coordinate system. World coordinate systems and view 
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geometric objects. Without this ability, CAD 
programs wouldn't be able to convert world 
coordinate descriptions of objects to window 
coordinates and correctly display images of the 
objects. Nor could they provide us with the 
ability to edit graphical images. 

Points and line segments constitute almost 
all of the geometric objects used in CAD 
systems. To manipulate points and lines, we 
need to know how to: 



Add and subtract vectors. 

Multiply and divide a vector by a number. 

Multiply a vector by a matrix. 

Multiply two matrices. 

Find distances between points in the plane. 

Find the equation of a line which passes through 

two points. 

Determine the point where two lines intersect. 
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coordinate systems are almost always different. In Intuition 
and most other window systems, the view coordinate system 
has its origin in the upper, left corner of the windows, and y 
coordinate values are positive below the origin. 

Two of the basic tasks which any CAD system has to 
perform are converting world coordinates to view coordinates, 
and converting view coordinates back to world coordinates. 
Three other basic operations CAD systems apply to geometric 
objects are scaling, translations, and rota- 
tions. Scaling is used to "zoom in' and ^^^^^^_ 
"zoom out". Scaling makes objects appear 
bigger or smaller. Translations are how 
objects are moved from one place to another. 
"Panning" is also accomplished using 
translations. Rotations turn objects around, 
over, and upside down. Figures two, three, 
and four, are representations of these three 
operations. All of these basic tasks are 
performed using geometric transformations 
on vectors. To understand how transformations work, we need 
to look at a few mathematical formulas and techniques. 

CAD SYSTEM MATHEMATICS 

Cartesian coordinate systems are very useful for determin- 
ing where points are located, determining distances between 
locations, and describing geometric objects in terms of points 
on the object. But they do much more than just this. They also 
permit us to apply algebraic techniques and formulas to 



We'll start out with the rules for vectors and matrices, 
since these are the critters used to transform geometries in 
CAD systems and since the transformation procedures use the 
rules. We'll get to 5, 6, and 7 in a little while. 

1 stated above that vectors were similar to Cartesian 
coordinates. So (x,y) can be either two-dimensional Cartesian 
coordinates or a two-dimensional vector. Another notation for 
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representing vectors is [ x y ]. In this notation, the vector is 
called a row vector, since the elements defining the vector are 
all on the same row. An alternate representation for the same 
vector is 



To multiply (divide) a vector by a number: Multiply 
(divide) each element of the vector by the nu?nber. 

Using this rule, 

a * [xl yl] - [ a*xl a*yl ] 

and 



[xl yl] / a = [ xl/a yl/a ] 

Pretty simple so far! Let's complicate things by looking at 
matrices and the rules for them. A matrix is a table of values, 
organized into rows and columns. A matrix is also a collection 
of vectors. Here is a 2x2 (two rows by two columns) matrix: 



Col 1 Col 2 



Row 1 
Row 2 



mil ml2 
m21 m22 



Where mil is the element at row 1, column 1; ml 2 is the 
element at row 1, column 2; m21 is the element at row 2, 
column 1; and m22 is the element at row 2, column 2. Notice 
that the elements of a matrix are subscripted: the subscripts 
indicate the row (first subscript) and column (second sub- 
script) where the element is located. 
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Figure Four 



A rectangle 
(from figure one) 
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system 



This is called a column vector, since the 
elements are all placed in a single column. 
The two notations are equivalent, and 
convenience or mathematics dictates which is 
used at any given time. 

Suppose we have two row vectors, [xl 
yl] and [x2 y2]. Here is the rule for adding 
and subtracting vectors: To add (subtract) two 
vectors: Add (subtract) the corresponding elements of each vector. 

Using this rule, 

[xl yl] + [x2 y2] = [ xl+x2 yl+y2 ] 



and 



[xl yl] - [x2 y2] = [ Xl-x2 yl-y2 ] 

The rule for adding and subtracting vectors may lead you 
to believe that vectors can be multiplied and divided in about 
the same way. This is not true! However, it is easy to multiply 
or divide a vector by a number. Here is the rule: 
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Now suppose we have a matrix, A, and another matrix, B, 
and we want to multiply the matrices. The first requirement is 
that we can multiply the matrices. Matrix multiplication is only 
defined if the number of columns in the first matrix is the same 
as the number of rows in the second matrix. So if A has 2 rows 
and 3 columns, and B has 3 rows and 2 columns, then A * B is 
legal. The product of two matrices is another matrix. The 
number of rows in the product matrix will be equal to the 
number of rows of the first matrix, and the number of columns 
in the product matrix will be equal to the number of columns 
in the second matrix. So if C = A * B, then C will have 2 rows 
and 2 columns. A is a 2x3 (two by three) matrix, B is a 3x2 
matrix, and the product, C is a 2x2 matrix. Let's see how matrix 
multiplication is actually done: 



all al2 al3 
a21 a22 a23 x 



bll 


bl2 


b21 


b22 


b31 


b32 



ell cl2 
C21 c22 



We only need to know a few more things about matrix 
multiplication before seeing how matrices are used to trans- 
form geometric objects. First, the order in which matrices are 
multiplied is important. If we have a matrix M and another 
matrix N, M x N is almost never equal toNxM. In fact, unless 
both M and N have the same number of rows as columns, one 
of the multiplications is not even defined! Second, there is no 
such thing as division of one matrix by another matrix or 
vector. So, if we multiply M times a vector v and get a vector c, 
we can't just divide M by c to find the vector we started with. 
To do this, we have to find a matrix called an INVERSE matrix. 

An inverse matrix, M', is defined to be a matrix which, 
when multiplied by another matrix M, will produce a special 
matrix called an IDENTITY matrix. The identity matrix is a 
square matrix: it has the same number of rows and columns. 
All entries of the identity matrix are zero, except for the 
diagonal elements, which are equal to 1 . Here is a 3x3 identity 
matrix: 



ell - all * bll + al2 * b21 + al3 * b31, 

cl2 • all * bl2 + al2 * b22 + al3 * b32, 

c21 - a21 * bll + a22 * b21 + a23 * b31, 

c22 = a21 * bl2 + a22 * b21 + a23 * b31 



1 
10 
1 



As you can see from the example, each element of the 

product matrix is the sum of the products of elements from a 
row of the first matrix and the corresponding column of the 
second matrix. For this reason, matrix multiplication is called 
"row-column multiplication". Rather than state a rule for 
matrix multiplication, here is an algorithm for multiplying two 
matrices: 

input: matrix A which is in x n, 
matrix B which is n x k 
output : product matrix C which is m x k 

do for i = 1, i <= m 
do for j = 1, j <=■ n 
set c(ij) =0 
do for 1=1, 1 <= n 
set c(ij) = c(ij] + a(il) * b(lj) 

It should be apparent from this algorithm that computers 
can multiply two matrices a lot easier than humans can! 

Multiplying a matrix times a vector is done the same way 
as multiplying two matrices: we write the vector as a column 
vector and treat it as a matrix with n rows and one column. So, 
if a vector with 3 elements is multiplied by a 2x3 matrix, the 
product will be a 2x1 matrix, which is a column vector with 2 
rows. Here is how the multiplication looks: 



mil ml2 ml3 
m21 m22 m23 



vl 
v2 

v3 



mllvl + ml2v2 + ml3v3 
m21vl + m22v2 + m23v3 



This matrix is called an identity matrix because, if another 
matrix is multiplied by it, the matrix is not changed by the 
multiplication. Identity matrices are frequently denoted by just 
writing "I" to mean any identity matrix. For a matrix to have 
an inverse, the matrix has to be a square matrix. It is important 
to keep in mind that even if a matrix is square, it may not have 
an inverse matrix. But, if there are two matrices, A and B, both 
n x n, and A * B = I, then A is the inverse of B, and B is the 
inverse of A. 

If we can find an inverse matrix, we can solve the problem 
of reversing a transformation which was applied to a vector. So 
if a vector has been transformed with a matrix A (c = A * v), we 
can find out what the original vector was by multiplying c by 
the inverse of A (v = A' * c), 

TRANSFORMING WORLD COORDINATES 

Three types of matrices are used in CAD systems to 
transform world coordinates. The three transformation 
matrices are a scale matrix, a rotation matrix, and a translation 
matrix. 

Figure two shows how the rectangle in figure one will 
look after it is scaled. Looking at the rectangle in figure two, 
we can see that multiplying the coordinates of an object to be 
scaled will either "stretch" the object or "shrink" the object. 
Multiplying coordinates by a number greater than one scales it 
up, and multiplying by a number between zero and one scales 
it down. The number that is used to multiply a coordinate is 
called a scale factor. So if we have a pair of coordinates we 
want to scale, the way to do it is to multiply the x coordinate 
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by an x scale factor, and multiply the y coordinate by a y scale 
factor. Both scale factors can be the same value, but we want a 
technique which will let us apply different scale factors to each 
coordinate. The easiest way to do this is with a scaling trans- 
formation matrix, which looks like this: 



sx 01 

sy 



If a set of coordinates are multiplied by this matrix, the 
result will be the scaled coordinates. Here is the formula for 
the multiplication: 



SK 

sy 



sx 
sy 



Let's see how the coordinates of the rectangle in figure one 
were scaled so that the width of the rectangle became half if s 
original width, and the height stayed the same. The x scale 
factor to do this is .5, and the y scale factor is 1. Plugging these 
values into the scale matrix and multiplying the vectors 
corresponding to the left and right top corners of the rectangle 
yields: 



.5 
l 

.5 o 

1 



-2 + 
+ 



I 
2 ■ 



2 + 
+ 2 



-2 
2 

2 

2 



Now, if the point is rotated counterclockwise by an angle, 
ang2, by adding the angle to the original angle and using a 
trigonometric identity for the cosine and sine of the sum of two 
angles, the formulas become: 



x = r * cos(angl+ang2) 
y = r * sin(angl+ang2) 



x * cos(ang2) - y * sin(ang2) 
x * sin(ang2) + y * cos(ang2) 



The expanded formulas are exactly what we need to build 
a rotation matrix which will rotate a point by any angle! Here 
it is: 



cos (a) 
sin (a) 



-sin (a) 
cos (a) 



If a column vector is multiplied by this matrix, the result 
will be a vector containing the rotated coordinates. Here is the 
multiplication: 



cos (a) 
sin (a) 



-sin (a) 
cos (a) 



x * cos (a) - y * sin (a) 
x * sin (a) + y * cos (a) 



Let's rotate the rectangle of figure one by 90 degrees to see 
how rotation matrices work. Doing this will produce the 
coordinates for the rectangle in figure 3. The cosine of 90 
degrees is 0, and the sine of 90 degrees is 1. Plugging these 
values into our rotation matrix and multiplying the two top 
corner coordinates of the rectangle yields: 



Here is how the array of coordinates for the rectangle 
looks after the scaling is complete: 

Index: 0123456789 

Coordinate: xyxyxyxyxy 
Value: -2 2 2 2 2-2-2-2-2 2 



-4 
2 = 

-; 

2 ■ 



0-2 
-4+0 

0-2 
4 + 



-2 
4 



This is the array of coordinates after each point is rotated: 



Rotation matrices are constructed using formulas from 
trigonometry. Rotating a point is equivalent to moving the 
point in a circle around some other point. If we have a circle in 
a Cartesian coordinate system with radius, r, and the center of 
the circle is located at the origin, (0,0), then the formulas for the 
(x,y) coordinates of any point on the circle are: 

x = r * cos(angl), y ■ r * sin(angl) 

where angl is the angle of inclination of the point in radians 
with respect to the x axis. 



Index: 0123456789 

Coordinate: xyxyxyxyxy 
Value: -2-4-2 4 2 4 2-4 -2 -4 

The only other transformation matrix we need for a 
complete set of transforms is a translation matrix. Translation 
is just a different word for moving an object. It should be 
pretty obvious from figure four that all we need to do to move 
a point is to add offsets (translations) to the coordinates of the 
point. The formulas for doing this are: 

x = x + x translation, y = y + y translation 
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The only problem with this is that adding translations to 
coordinates doesn't fit in with multiplication of 2x2 matrices. 
To solve this problem, we increase the dimension of our matrix 
and use what is known as HOMOGENEOUS coordinates. 
Instead of using just [ x y ] to represent a point, we use an 
"extra" coordinate and ignore it. The extra coordinate is equal 
to 1 (it doesn't have to be, but for two-dimensional graphics, 1 
works just fine). So a point becomes I x y 1 ] in homogeneous 
coordinates. Since the point is represented with three elements, 
the transformation matrices for homogeneous coordinates 
have to be 3x3 matrices. If we add a zero term in the formulas 
for translation, we can see how our translation matrix should 
look: 

x = x + + x translation 

y = y + + y translation 
1 = + + 1 

Writing these formulas as a matrix gives: 



1 xtrans 
1 ytrans 
1 



If a homogeneous coordinate vector is multiplied by this 
matrix, the coordinate will be moved by "xtrans" along the x 
axis and by "ytrans" along the y axis. The multiplication looks 
like this: 



1 xtrans 
1 ytrans 
1 



x + + xtrans 
y + + ytrans 
+ + 1 



Multiplying the top, corner coordinates of our rectangle 
by a translation matrix with xtrans = 1 and ytrans = 1 will give 
us the translated coordinates, as follows: 



10 1 
1 1 
1 


X 


-4 
2 

1 


= 


-4+0+1 
+ 2 + 1 
+ + 1 


= 


-3 

3 

1 


10 1 
Oil 
1 


X 


4 
2 

1 


= 


4 + + 1 
+ 2 + 1 
+ + 1 


= 


5 
3 

1 



Ignoring the extra coordinate, this is the array of coordi- 
nates after each point is translated: 

Index: 0123456789 

Coordinate: x y x y x y x y x y 
Value: -3-1-3 3 5 3 5-1 -3 -1 



sx 




sy 




1 







1 tx 




1 ty 




1 



We have now derived all the matrices needed to manipu- 
late two-dimensional objects, and have seen how to use each of 
them to perform the three basic CAD operations of scaling, 
rotating, and translating world coordinates. Rewriting the scale 
matrix and the rotation matrix for homogeneous coordinates, 
the three matrices are: 



cos (a) -sin (a) 

sin(a) cos(a) 

1 



All of the examples have used single transformations. If 
we want to scale, rotate, and translate a point, do we have to 
apply the transformations separately? Do we have to first 
multiply the point by a scale matrix, then multiply the scaled 
point by a rotation matrix, and finally, multiply the scaled and 
rotated point by a translation matrix? No, we don't; the three 
transformation matrices can be multiplied together, and then 
the point to be transformed can be multiplied by the overall 
matrix. The scale matrix is created and multiplied by a rotation 
matrix, then the product matrix is multiplied by a translation 
matrix. The final product matrix combines all three transfor- 
mations into a single matrix. Then, when a vector is multiplied 
by the overall transformation matrix, the vector will be scaled, 
rotated, and translated all at once! 

So far we've developed the transform matrices to convert 
a geometric object modeled with vectors from one world 
coordinate representation to another (transformed) world 
coordinate representation. To display the model in an Intuition 
window and to interact with the model using a pointing 
device, we need to know how to represent the model in the 
window's coordinate system. We'll now see how the world 
coordinate representation of a geometric object is transformed 
to a window coordinate representation, and vice versa. 

WINDOWS, VIEWPORTS, 

AND VIEWING TRANSFORMATIONS 

Suppose you are designing a house with a CAD system. 
Naturally, you would like for the dimensions of your design to 
be in feet and you would like to work with feet instead of 
pixels while creating and modifying your design. In CAD 
terms, you want to work in object space and you want the 
dimensions of your design to be in world coordinates. How- 
ever, the unit of measure for Intuition screens and windows is 
pixels, and the image of the design which is displayed is in 
pixel coordinates. The image of the design is in image space 
and the image's dimensions are in view coordinates. 

Computers can't display geometric objects in object space, 
only in image space. So CAD systems have to convert the 
world coordinate model to an image in view coordinates to 
display it. The conversion is performed with a viewing 
transformation. Figure five depicts the overall transform 
process which occurs in CAD systems. 
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Figure Five 

The Transform 
Pipeline 



Designers work with a model in world 
coordinates: moving parts, scaling parts, and 
rotating parts using world coordinate trans- 
forms. The CAD system then applies a viewing 
transformation to the world coordinates to 
create an image of the object in view coordinates. 
The image is then displayed or plotted. To enable 
objects to be picked with a pointing device, the CAD system 
has to reverse this process: the pick coordinates are view 
coordinates which have to be converted back to world coordi- 
nates. 

Viewing transformations map a rectangular area in world 
coordinate space onto a rectangular area in view coordinate 
space. The rectangular areas are called windows. The area in 
world coordinates is a world window, and the corresponding 
area in view coordinates is a view window. Figure six shows 
how a world window corresponds to a view window being 
displayed in an Intuition window. Viewing transforms are 
calculated from the coordinates of the world window and the 
coordinates of the view window by mapping the corners of the 
world window to the matching corners of the view window. A 
view transform for figure six would be calculated so that 
(wxl,wyb) is transformed to (vxl,vyb) and (wxr,wyt) is 
transformed to (vxr,vyt). 

Let's use some actual numbers for the coordinates in 
figure six and see what is involved in creating a view trans- 
form. Suppose the house is designed using feet, and the lower, 
left world window coordinates are (T,2) and the upper, right 
coordinates are (21,42). The height of the world window is then 
20 feet, and the width is 40 feet. Suppose the Intuition window 
is 80 pixels high and 220 pixels wide, and that the lower, left 
view window coordinates are (10,70) and the upper, right view 
window coordinates are (210,20). The view window is then 50 
pixels high and 200 pixels wide. Here is a summary of the 
coordinates and dimensions: 



World Coordinate Data 



World Coordinate Transform 



View Coordinate Transform 



View Coordinate Data 



Multiplying the scale factor times world dimensions will 
produce the desired view dimensions. The only problem with 
this formula is that our world y coordinates increase in the 
"up" direction and our view y coordinates increase in the 
"down" direction: wyt is greater than wyb, but vyt is less than 
vyb. We can include information about direction in our scale 
factors by using the following formulas: 

width scale factor = (vxr - vxl) / (wxr - wxl) 
height scale factor = (vyt - vyb) / (wyt - wyb) 

We can find the scale factors for our example by plugging 
the example values into these formulas: 

width scale factor = (210 - 10) / (21 - 1) = 10 
height scale factor = (20 - 70) / (42-2) = -5/4 



World window: (wxl, wyb) = (1,2), (wxr, wyt) = (21,42) 

world width = 20, world height =40 

View window: (vxl, vyb) = (10, 70} , (vxr, vyt) = (210,20) 

view width = 200, view height = 50 

To make the dimensions of the world window the same as 
the dimensions of the view window, we need to find width 
and height scale factors which can be multiplied times the 
world dimensions to yield the view dimensions. Here is the 
formula we want: 

view dimension = world dimension * scale factor 

Solving this formula for the scale factor gives 

scale factor = view dimension / world dimension 



These scale factors will map directed distances relative to 
the world coordinate origin onto directed distances relative to 
the view coordinate origin. They will also make directions in 
view coordinates correspond to directions in world coordi- 
nates. 

Take another look at figure six (see page 17). The world 
window is not located at the world coordinate origin, and the 
view window is not located at the Intuition window origin. So 
if we just multiply world coordinates by these scale factors, we 
won't get the correct view coordinates! However, if we first 
move the world window so that it is located at the world 
coordinate origin BEFORE multiplying by the scale factors, 
we'll get correctly scaled view coordinates, relative to the view 
coordinate origin. Since the view window is not located at its 
origin (the top, left corner of the Intuition window), we then 
move the view coordinates to their location inside the view 
window. 
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The translation values to move the world window so that 
it is located at the world coordinate origin can be found by 
subtracting the lower, left world window coordinates from the 
window corner coordinates. If the world coordinates are first 
translated then scaled, the resulting view window will have its 
lower, left view window coordinates located at the Intuition 
window origin. By adding the view window lower, left 
coordinates to the calculated view coordinates, the view 
coordinates will be moved to their correct position in the 
Intuition window. 

Summarizing the above discussion, three steps are 
required to transform world coordinates to view coordinates: 

Step 1: world coordinates are moved so that the specified 
world window is located at the world coordinate origin. This 
step is accomplished with a translation matrix, using the lower, 
left world window coordinates for the translation values. The 
translation matrix is: 



1 -wxl 
1 -wyb 
1 



Step 2: world coordinates are converted to view coordi- 
nates, relative to the view window origin. This step is accom- 
plished with a scale matrix: 



sx 











sy 











: 



where ... 

sx = (vxr-vxl)/ (wxr-wxl) 
sy = (vyt-vyb) / (wyt-wyb) 



This matrix will work just fine as long as view distances 
along the x axis and the y axis are equal, and as long as the 
width and height scale factors are equal. 

Unfortunately, this is not usually the case: 100 horizontal 
Intuition pixels is not the same length as 100 vertical Intuition 
pixels, and the scale factors are usually not equal because the 
world window and the view window are generally not 
squares. 

We need to correct the scale factors to produce equal 
scaling in x and y, and to compensate for different horizontal 
and vertical pixel resolutions. The scale factors can be made 
equal by simply using the smaller of the two scale factors, and 
the difference between horizontal and vertical view distances 
can be compensated for by using a value called an aspect ratio. 
The x aspect ratio is the number of pixels per unit in x divided 
by the number of pixels per unit in y, and the y aspect ratio is 
the number of pixels per unit in y divided by the number of 
pixels per unit in x. 

Where do we get the values needed to calculate the aspect 
ratio? Thanks to the Amiga software designers, the values are 
stored in the GfxBase structure in the member variables named 
"NormalDPMX" and "NormalDPMY". These variables contain 
the number of dots per meter along the x and y axes for an 
interlaced screen. After a GfxBase structure pointer has been 
set by opening the graphics library, the x aspect ratio for 
Intuition screens and windows can be found by dividing 
NormalDPMX by NormalDPMY. For non-interlaced screens, 
NormalDPMY needs to be halved before the aspect ratio is 
determined. The y aspect ratio is just the reciprocal of the x 
aspect ratio. 

We can now specify how the translation and scale values 
for the view transform are calculated. The translation values 
are calculated by scaling the world coordinate translations and 
combining them with the view coordinate translations: 



Step 3: view coordinates are moved so that the view 
window is positioned at the desired location in the Intuition 
window. This step is accomplished with a translation matrix, 
using the lower, left view window coordinates for the transla- 
tion values: 



xtrans = vxl - wxl * (vxr - vxl)/(wxr - wxl) 
ytrans = vyb - wyb * (vyt - vyb) / (wyt - wyb) 

The scale values are calculated with the following algo- 
rithm, which finds the smallest scale factor in x or y and 
corrects the appropriate value using the x aspect ratio: 



1 vxl 
1 vyb 
1 



The above three matrices can be combined by matrix 
multiplication, resulting in the following overall view transfor- 
mation matrix: 



sx 





-sx * wxl + vxl 





sy 


-sy * wyb + vyb 








1 



Input: world window coordinates, 

view window coordinates, 

x aspect ratio 
Output: translation values and scale values 

for a view transform 



Step 1: Find directed view and window distances: 



Set vheight ■ vyt - vyb 
Set vwidth = vxr - vxl 
Set wheight = wyt - wyb 
Set wwidth = wxr - wxl 
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Step 2: Find absolute scale factors 

If ABS (vheight) is less than ABS (vwidth) , 

Set yscale = ABS(vheight/wheight) 

Set xscale ■ yscale * xaspect 

Else 

Set xscale = ABS (vwidth/wwidth) 

Set yscale - xscale * xaspect 

Step 3: Correct the sign for the scale factors 

If vwidth and wwidth have different signs, 
Set xscale = xscale * -1.0 

If vheight and wheight have different signs, 
Set yscale = yscale * -1.0 



We then plug the calculated values into a view transform 
matrix: 



xscale xtrans 
yscale ytrans 
1 



Figure Six 



World and View 
Windows 



(wxl,wyb) 



y \| 



(wxr, wyt) 
World Window 



(vxLvyb) 



Intultftn Wkidow 



Gcagoi 1 | | GQg;3tT" 



(vxr, vyt) 



View Window 



THE TRANSFORMATION AND MATRIX PROCEDURES 

Listing one (all listings are on the AC'S TECH disk) contains 
procedures which implement all of the above transformations, 
manage a transform structure, and handle the details of 
transforming coordinates. Listing one has almost all of the 
procedures needed for creating vector-oriented two-dimen- 
sional graphics programs. Listing two is the include file which 
defines the transform structure, declares the transform 
procedures, and defines some useful macros. The procedures 
in listing one can be compiled and linked with a graphics 
program, or can be placed into an object module library for 
later linking. 

Here is a description of how the procedures work, and 
how to use them. The linkages are documented with the 
procedure listings. 

The basic transform data structure is defined in 
"transform.h". It is typedef'ed as "transform2_t". It stores the 
scale values, translation values, and rotation value for a 
transform, and also stores the transformation matrix and its 
inverse. A pointer to a transform2_t structure is required as 
input for the transform procedures. The transform procedures 
are setWor!dTransform( ), getTransform( ), point2dForward( ), 
and point2dInverse( ), worldWindowToViewWindow( ), and 
setViewTransform( ). 

SetWorldTransform{ ) initializes the transform2_t struc- 
ture, creates a world transform matrix, and finds the inverse 
transform matrix. The transform matrix is created so that 
coordinates will first be scaled, then rotated, and finally 
translated. You may want to experiment with creating the 
transform in a different order; for example, rotating first, then 
scaling. The results may surprise you! 

GetTransformC ) is a simple utility procedure which just 
returns the current transform values stored in the transform2_t 
structure. Of course, you can access these values directly, but it 



is good programming practice to isolate access and update of 
data structures in a single place. This way, if the structure 
changes, the impact on your program will be minimized! 

Point2dForward( ) and point2d!nverse( ) are the two 
work-horse procedures for transforming coordinates. 
Point2dForward( ) transforms a set of coordinates and returns 
the transformed coordinates. The transform is performed by 
multiplying the coordinates by the transform matrix. 
Point2dInverse( ) converts a set of transformed coordinates 
back to the original coordinates (there may be round-off or 
truncation error, depending on the transform and the coordi- 
nates, so the coordinates may not be exactly the same as the 
original ones). Point2dInverse{ ) is just like point2dForward( ), 
except the transformed point is multiplied by the matrix which 
is the inverse of the transform matrix. 

WorldWindowToViewWindow( ) and setViewTransform( 
) are view transform procedures. The view translation and 
scale values which will transform a world coordinate window 
to a view coordinate window are calculated in 
world WindowToViewWindow( ), using the algorithm 
described above. The calculated values are then sent to 
setViewTransform( ), which uses the values to initialize a 
transform structure and build a view transform matrix and its 
inverse matrix. In addition to the view translation and scale 
values, a rotation angle can also be sent to setViewTransform( 
). The view rotation angle will cause the entire view window to 
be rotated. After the transform structure has been initialized in 
setViewTransform( ), it can be used with point2dForward( ) to 
transform world coordinates to view coordinates, with 
point2dInverse( ) to transform view coordinates back to world 
coordinates, and sent to getTransform( ) to access its values. 

To use the transform procedures, include the file 
"transform.h" in your program. Allocate a transform2_t 
structure, either statically or dynamically. Call K 
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setWorldTransform( ), sending it the transform and transform 
values. Then, when you are ready to transform a point, call 
point2dForward( ), sending it the transforrn2_t structure. It 
will do the work for you, and return the transformed coordi- 
nates. To convert the transformed point back to original 
coordinates, call point2d!nverse( ). 

The transform matrix and its inverse matrix are created 
using the matrix procedures mat2dlnit( ), mat2dScale( ), 
mat2dTranslate( ), mat2dRotate( ), and matlnvert( ). These 
procedures can be used without the transform procedures, if 
you are interested in experimenting with them, or creating 
your own transform structures. The matrices are actually 
stored in singly-dimensioned arrays. For two-dimensional 
homogeneous transforms, nine elements are needed, since the 
matrix is a 3x3 matrix. So you can understand the code, here is 
how the matrix is stored (numbering from so indexes 
correspond to "C" indexes): 



Mat2dRotate( ) multiplies the transform matrix by a 
rotation matrix: 



row 
row 1 
row 2 



col 

array [0] 
array [3] 
array [6] 



col 1 



col 2 



array(l] array[2] 
array [4] array [5] 
array [7] array [8] 



Any two-dimensional matrix can be stored this way. The 
array index for an entry at row i, col j (matrix[i][j]) is i * number 
of columns + j. So the array index for the entry in matrix[l][2] 
is 1 * 3 + 2 = 5. 

Mat2dlnit( ) initializes the transform matrix by creating a 
3x3 identify matrix: 



10 
10 
1 



The overall transform matrix is then created by successive 
matrix multiplications of the transform matrix by scale, 
rotation, and/or translation matrices. 

Mat2dScale( ) multiplies the transform matrix by a scaling 
matrix: 



sx o 

sy 
1 



tOO tOl t02 
tlO til tl2 

1 



Mat2dTranslate( ) multiplies the transform matrix by a 
translation matrix: 



1 tx 




tOO tOl t02 


1 ty 


X 


tlO til tl2 


1 




1 



cos (a) -sin (a) 

sin (a) cos (a) 

1 



tOO tOl t02 

tlO til tl2 

1 



Finally, matlnverK ) is a matrix inversion procedure which 
can find the inverse of an n x n matrix (if the matrix has an 
inverse). I'm not going to describe matrix inversion, but you 
can find the algorithm in any textbook about linear algebra. 
The algorithm used is called "Gauss-Jordan elimination with 
partial pivoting". 

THE TRANSFORM DEMONSTRATION PROGRAMS 

Demonstration programs which show how to use the 
transform procedures are presented in listing three and listing 
four. The program in listing three shows how the transforms 
for scaling, rotating, and translating model geometric objects 
are used. The program in listing four shows how to set up and 
use view transforms. 

The program in listing three, tforml.c, displays a set of 
coordinate axes and a polygon centered in an Intuition 
window. Four gadgets, labeled 'Translate", "Rotate", "Scale", 
and "Reset" are displayed in the window, and each time a 
transform gadget is selected, that transform is applied to the 
polygon. 

The 'Translate" gadget is used to move the polygon in 
increments of 100 world coordinate units. Each time the gadget 
is selected, the polygon will be moved right, left, up, or down. 
Selecting the "Rotate" gadget rotates the polygon counter- 
clockwise by 30 degree increments until it turns all the way 
around. It then rotates the polygon clockwise in -30 degree 
increments. The "Scale" gadget is used to scale the polygon 
using scale values between ,4 and 2.0, in increments of .4. The x 
and y scale values are calculated separately. Selecting the 
"Reset" gadget restores the polygon to its original, 
untransformed position and size. The program demonstrates 
what effect each separate transformation has, and also shows 
the effect of combinations of transformations. 

Tform2,c, the program in listing four, is similar to 
tforml.c, except all transformations are performed with a view 
coordinate transform instead of world coordinate transforms. 
The entire model world, instead of individual objects, is 
transformed. 

The program starts by displaying three geometric objects 
and a set of coordinate axes centered in a view window. Two 
pushbutton gadgets are displayed in the lower, left corner of 
the Intuition window. One gadget is labeled "Full Display", 
and the other is labeled "Set Transform". 

When the "Full Display" gadget is selected, the program 
recalculates the data for the view transform so that the entire 
world window will be displayed in the Intuition window. The 
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"Full Display" scale for both axes is set to scale 1 . This is not 
the actual scale value for the view. Instead, it is a scale value 
relative to the size of the current view window. Thus, it is a 
base value for increasing or decreasing the view scale. This is 
done by multiplying the actual x scale and y scale values by 
the relative scale value. 

When the "Set Transform" gadget is selected, the trans- 
form requester "pops up" in the Intuition window. The 
transform requester contains labeled string gadgets for 
displaying current transform values and for entering new 
transform values. 

It also contains an "Accept" pushbutton and a "Cancel" 
pushbutton. Transform values are modified by selecting the 
appropriate string gadget and typing in the new value. When 
the "Accept" button is selected, the requester is "popped 
down", the transform values are read from the string gadget 
buffers, the view transform is updated, and the view is 
redisplayed using the updated view transform. When the 
"Cancel" button is selected, the program simply removes the 
requester. The program is stopped by selecting the window 
"Close" gadget. 

The executable programs are created by compiling and 
linking the programs with the transform procedures. The 
Lattice commands to compile and link the programs are: 






-Lm tforml. c transform, c" 
-Lm tform2.c transform. c" 



HOW THE PROGRAMS MANAGE DATA 
AND HANDLE EVENTS 

Both programs use several neat programming "tricks". 
First, linked, hierarchical-style data structures are used for 
describing and organizing the program's data. Second, 
indirectly executed (via function pointers) "event handler" 
procedures are used with the gadgets. These features are 
described in the next several paragraphs. 

The program data and state information is organized in a 
hierarchy. The top level of the hierarchy is a "world^t" 
structure. A pointer to this structure is stored in the 
"UserData" field of the Intuition window in which the data is 
being displayed. Storing the top-level structure pointer with 
the window allows us to access all of our data and state 
information through the Window pointer. 

The world_t structure contains an overall description of 
the entire set of world coordinates, and a pointer to the view 
transform structure. It also contains a pointer to a linked list of 
all the world coordinate geometric objects. In addition to the 
list of world objects, this structure contains the minimum and 
maximum extents of the world coordinated system. The 
extents are used to determine how the world coordinates will 
be scaled to fit in the window. 

The objects are stored in an "objecM" structure, which is 
simply a polygon descriptor record. The actual coordinates for 
each geometric object are stored in a singly-dimensioned array 



of sequential x,y coordinate pairs. The object_t structure 
contains a pointer to the object's coordinate array, and the 
dimension of the array. The object_t structure used in tforml 
also contains a pointer to an individual world transform for 
each object. 

Function pointers are used to process gadget events. A 
pointer to the procedure which is called from the event 
processing loop when a gadget is selected is stored in the 
gadget's "UserData" structure. Whenever a "GADGETUP" 
event occurs, the input handler retrieves the function pointer 
and calls the procedure using the function pointer. Each 
gadget handler procedure has only one call argument: the 
pointer to its window. Since the window pointer contains a 
pointer to the worId_t structure, the handler procedure can 
access all the information it needs to do its job from the 
window pointer. 

To make casting the pointer from an Amiga APTR to a 
function pointer easier, a typedef for the function pointer is 
used. By using event handler function pointers, we can 
simplify event processing and eliminate "switch" type code 
which requires detailed knowledge of the program's control 
and data structures. 

PROGRAM CONTROL FLOW 
AND DRAWING PROCEDURES 

Both programs work basically the same way. The main( ) 
procedure initializes data structures, opens an Intuition 
window, calculates the initial view transform for the window, 
displays the model world, and then calls handlelnput( ). 

Window gadgets are initialized and fuction pointers are 
attached to the gadgets in initWinGadgets( ). Tform2 also calls 
initTfRequester( ) to create the 'Set Transform' requester and 
its gadgets. Both initWinGadgets( ) and initTfRequesterC ) are 
straight-forward, execpt for the "static" structures defined in 
initTfRequesterC )• 

The structures are "static" to prevent them from being 
overwritten after the procedure returns, since they contain 
data for the requester and its gadgets used throughout tform2. 
Remember that local variables in a procedure which are not 
static are allocated from the stack when the procedure is 
entered, and the space is made available for reuse when the 
procedure returns! 

In tforml, the view transform is calculated in 
find ViewTransformC ). This procedure is called the first time 
the window is displayed, and then again each time a 'refresh 
window' event is received. In tformz, the view transform is 
calculated in fullDisplayC ) each time the "Full Display" gadget 
is picked. 

The input handler receives input events, retrieves the 
event handler function pointer, and calls the event handler 
procedure. This process continues until the window 'close' 
gadget is picked. In tforml, HandlelnputC ) is only concerned 
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with three events: CLOSEWINDOW, GADGETUP, and 
REFRESHWINDOW. In tform2, two additional events, 
REQSET and REQCLEAR, are processed. 

When the first requester in a window is popped up, 
Intuition sends out a REQSET event, and when the last one is 
popped down. Intuition sends out a REQCLEAR event. Of 
course, to receive these events, we have to request them by 
setting the IDCMP flag in the NewWindow structure when we 
open a window. 

The reason we want to get requester events is to prevent 
the window from being closed while a requester is displayed. 
Otherwise, the program could end and leave the requester just 
hanging around. If handlelnputt ) receives a CLOSEWINDOW 
event, and no requester is being displayed, the input loop is 
ended, any messages are reply'ed to, and the procedure 
returns to main{ ). If a requester is being displayed, the 
CLOSEWINDOW event is just ignored. When a 
REFRESHWINDOW event is received, drawAlK ) is called to 
redisplay the window. Finally, if a GADGETUP event is 
received, handlelnput( ) gets the function pointer to the gadget 
handler and calls the procedure using the function pointer. 

The drawing procedures are drawAHC ), eraseAIK ), 
drawAxis< ), and drawObject( ). DrawAlK ) sets up and installs 
a clip region in the window, calls drawAxis( ), then traverses 
the list of objects stored with the window, calling drawObject( 
) to actually transform and display each object. 

Clip regions and clipping procedures are part of the 
Amiga software. The structures related to clipping are defined 
in the Amiga graphics include files "clip.h", "regions.h", and 
"layers.h", and all but one of the clipping procedures are in 
"graphics.library". The exception is InstallClipRegionC ), which 
is in "layers.library". 

A clip region is basically a collection of rectangles tor 
restricting drawing; that is, no drawing will occur outside the 
clipping rectangles. The clipping procedures are very useful 
and are documented in the "Libraries and Devices" Rom 
Kernel Reference Manual. The reason drawAlK ) uses clip 
regions is to prevent drawing from occurring on top of the 
window's gadgets. EraseAIK ) just erases everything in the 
window by calling the graphics procedure RectFill( ). 

DrawObjecU ) retrieves the array defining an object's 
coordinates and loops through the array, transforming the 
coordinates and drawing lines connecting each coordinate 
pair. In tforml, the coordinates are transformed twice: first the 
world transform attached to the object is used to translate, 
rotate, or scale the object: then the view transform attached to 
the window is used to convert the coordinates to pixels. 

In tform2, only the view transform is used. 
Point2dForward( ) is called to perform both the world and 
view transforms. Notice that the world coordinates for the 
object being drawn in tforml are never modified by the 
transformation: we keep the original coordinates and just use 
the transformed coordinates for drawing into the window. 



DrawAxis( ) draws the coordinates axes through the 
world center coordinates, (0,0). Point2dForward is called to 
transform the world origin to pixel coordinates using the 
window's view transform. In tforml, drawAxis( ) simply 
draws horizontal and vertical lines for the axes. 

In tform2, the procedure is much more complicated. All 
the world information, including the coordinate axes, may be 
rotated by the view transform. When the axes are rotated, we 
don't know their starting and ending pixel coordinates. To find 
the start and end coordinates, we need to know where each 
axis intersects the sides of the view window. We have to use a 
little algebra and perform some coordinate transformations to 
find the intersect points. 

If we know two points, (x1,yl) and (x2,y2), we can find the 
equation of the line passing through the points. The general 
equation of a line through two points is: 

y = (y2-yl)/(x2-xl) * x - (y2-yl) / (x2-xl) * xl + yl 

If x2 - xl is 0, the line is vertical, and if y2 - yl is 0, the line 
is horizontal. If the line is not vertical, it intersects the y axis at 
the point (0,y) and if it is not horizontal, it intersects the x axis 
at the point (x,0). So, to find where it intersects the y axis, we 
set x equal to zero and solve for y: 

y = yl - (y2-yl)/(x2-xl) * xl 

To find where the line intersects the x axis, we set y equal 
to zero and solve for x: 



xl - (x2-xl)/(y2-yl) 



yi 



The above two equations are used in the version of 
drawAxis( ) in tform2 to find the points where the world 
coordinate axes intersect the sides of the view window 
rectangle. 

But the coordinate axes are in world coordinates and the 
sides of the view window rectangle are in view coordinates! 
The points have to be in the same coordinate system for the 
equations to work right. We solve this problem by transform- 
ing the corner coordinates of the view window rectangle to 
world coordinates. A view transform converts world coordi- 
nates to view coordinates, but its inverse transform will 
convert view coordinates to world coordinates. We just happen 
to have the inverse transform stored in our transform struc- 
ture, and we also have a procedure to use it. 

The corner coordinates of the view window are trans- 
formed to world coordinates by calling point2dInverse( ). 
DrawAxis{ ) then determines if the sides of the view window 
rectangle are horizontal and vertical in the world coordinate 
system. If so, the world coordinate origin is transformed to 
view coordinates and the axes are drawn as horizontal and 
vertical lines through the transformed origin. 
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Otherwise, the above equations are used to find the paints 
where all four view window sides intersect the x axis, and the 
points where all four sides intersect the y axis. The intersect 
coordinates are then sorted to find those closest to the origin. 
The intersect coordinates are transformed to view coordinates 
by calling point2dForward( ). The transformed intersect 
coordinates are then used to draw the axes. 

EVENT HANDLER PROCEDURES 

The event handler procedures which are called in tforml 
when a gadget is selected are rotate( ), scale( ), translate( ), and 
reset( ). These procedures erase the contents of the window, 
modify the world transform for the object, then redisplay the 
contents of the window. 

Tform2 also has four gadget event handler procedures. 
They are fullDisplay( ), setNewTransform( ), acceptValuesf, ), 
and cancelValues( ). When the 'Full Display' gadget is picked, 
fullDisplay( ), which was described above, is called. When the 
'Set Transform' gadget is picked, setNewTransformf ) is called. 
This procedure updates the view transform requester, pops up 
the requester, and returns control to handlelnput{ ). If the 
requester 'Cancel' gadget is selected, cancelValues( ) is called, 
and just pops down the requester. If the requester 'Accept' 
gadget is picked, acceptValues( ) is called, this procedure reads 



the new view transform values, pops down the requester, 
updates the view transform, and then erases and redisplays the 
window. 

Notice the relationship between setNewTransformf. ), 
acceptValuesf ), and canceIValues( ). SetNewTransform( ) is an 
event handler which is setting up the program for a call to 
another event handler, either acceptValuesf ) or cancelValues( 
). The gadget events are being 'chained together' through event 
handlers. We'll explore event chaining in more detail next 
time. 

SUMMARY AND PREVIEW 

We have now developed a data structure for storing two- 
dimensional transform data and a complete set of procedures 
for creating, updating, accessing, and using two-dimensional 
transforms. We have also developed techniques for processing 
input events using function pointers to 'event handler' 
procedures. We saw how to create and use world coordinate 
transforms and view transforms. 

Where do we go from here? Well, next time, we're going 
to see how to use event handlers with menus and the mouse so 
we can move, rotate, and resize objects by 'picking and 
dragging' them. We'll also implement a menu 'zoom' function, 
and implement 'panning' with a proportional gadget. 
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Interfacing 
Assembly 
Language 
Applications 
to ARexx 



by Jeff Glatt 



Amiga owners are hearing a lot of talk about ARexx. They've been told that ARexx can be used to add a sophisticated macro 
language to any program, or turn several applications from various companies into a single, integrated package that is more 
powerful than the individual components -working alone. There have been numerous articles describing hoiv an end-user can use 
ARexx, but unfortunately very little information that shows a programmer how to interface his program to ARexx. This article 
strives to do the following: 

1) Describes the ARexx server from the point of view of a programmer. 

2) Demonstrates how to add an ARexx implementation to a program (i.e. how to communicate with the ARexx server 
using ARexx structures). This demonstration is accomplished by describing a complete (but surprisingly simple) 
ARexx implementation added to my example 68000 assembly program. 



What's ARexx? 

ARexx is a programming language. In describing ARexx, I 
like to compare it to BASIC because most programmers are 
familiar with BASIC, and also because, like BASIC, ARexx is an 
interpreted language. Therefore, an ARexx program (often 
called a macro or script) is really just a text file which must be 
parsed and "executed" by some interpreter. Just as you need 
the Amiga BASIC interpreter to run your BASIC script, you 
need the ARexx interpreter (called the ARexx server) to run an 
ARexx script. The ARexx server comes in the form of a library 
called "rexxsyslib.library" and a program called RexxMast 
which loads and starts up a self-running process that can load 
and "execute" ARexx scripts. Furthermore, there is a program 



which the user can invoke from a CL1 in order to start an 
ARexx script's execution. Amiga ARexx is written and 
marketed by Bill Hawes. An end-user must obtain this product to 
use ARexx, either by itself or in conjunction with his own 
program. 

From hereon in, I will refer to the ARexx server/library as 
simply ARexx. 

Unlike AmigaBASIC, an ARexx script can be written using 
any text editor. The script consists solely of ascii characters, 
and each line ends with a newline character (10). There are no 
imbedded codes in the script that are required by the inter- 
preter. 
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There is also no "output window" for the interpreter. 
ARexx prints error messages to the CLI process window from 
where the script was started. From WorkBench, ARexx will 
create a DOS window when the script starts, and close it when 
the script is finished. 

ARexx has a built-in set of commands. For example, the 
SAY command prints text to the standard out handle ( usually 
the CLI window). There are commands for constructing loops, 
performing tests, evaluating mathematical expressions, 
reading/writing files, etc. The two areas where ARexx lacks 
are that it has no graphics and no audio commands whatso- 
ever. The extent of its graphics is printing text to the CLI. It has 
no intuition interface (i.e. can't open windows, post requesters, 
or support the mouse). 

The two most important differences between BASIC and 
ARexx are in the way that variables are treated, and in the fact 
that ARexx can send messages to any program that has a public port, 
and therefore control that program. 

All ARexx variables are in the form of strings. For ex- 
ample, if you set a variable, MyNum = 10, internally ARexx 
stores the value of MyNum not as a LONG, WORD, or BYTE 
value, but as the ASCII, null-terminated string of '10'. In other 
words, MyNum would be stored as the following 3 bytes: 
MyNum dc.b T/0',0 ; or 49,48,0 Note that ARexx has an 
internal mechanism for marking this as a numeric variable 
even though it is stored as a string. So the following two 
statements in an ARexx script are NOT the same: 

MyNum =10 
MyNum - '10' 

Although ARexx stores them both as identical strings, it marks 
the first as a numeric variable and the second as a string 
variable, two entirely different things. (Note that strings in an 
ARexx script are enclosed in quotes. Also note that unlike 
BASIC, ARexx string variables do not require any $ or other 
special symbol to distinguish them. ARexx intelligently 
determines the type of variable when it executes the script, so 
the user never declares variable types.) 

For details about ARexx's set of built-in commands, and 
information about using variables in an ARexx script, consult 
the ARexx Users Manual that is included with that product. 

How ARexx Controls Your Program 

As mentioned, ARexx can communicate with any program 
that has a public port, sending it "commands" that ARexx 
encounters in a user-written script. A program can also send 
"commands" and data to ARexx. Because of these capabilities, 
a program can use ARexx as an easy way to implement a 
powerful (but slow) user customizable macro language. ARexx 
scripts can be invoked from the program so that the user never 
even has to deal with the server directly, and it appears as if 
the macro features are "part of the program." Also, self- 



running demos of programs can be made by writing an ARexx 
script to control the program, then invoking ARexx upon this 
script within a startup-sequence. Finally, two or more pro- 
grams can pass data directly between each other via ARexx, 
creating an integrated environment. 

To allow ARexx to communicate with your program, the 
program must add a public Exec port (i.e. a port with a name) 
to exec's list of ports via Exec's AddPort function. You can also 
use the CreatePort function as listed in the Exec RKM on page 
B-5, but be sure to pass a portname string. Additionally, before 
creating and adding the port, you should make sure that there 
isn't already a port with this name in exec's list. You do this 
with the exec function, FindPort. If so, your program should be 
able to dynamically change its port name to something unique. 
Note: You cannot use the portname of 'REXX'. This is reserved 
for the ARexx server's own port. 

Once your program has added its port to exec's list, an 
ARexx script can send commands and arguments (data) to the 
program. ARexx does this by sending a message structure 
called a RexxMsg to your port. The RexxMsg contains an 
imbedded Exec message and looks like this: RexxMsg: 



;- The Stanford Exec message part 

del ;LU_SUCC (address of the previous message linked to this port) 

del ;LM PRED (address of the next message linked to this port) 

dc.b 5 ;Dl"TYPE (-KIHE55MEI 

dc.b ;Lt)_PRI 

del [LHJJAKE, could be the address of thenuli-tersninated name of your port] 

del [the address of your program's public port] 

dew 128 ;the size of the RexxMsg 

;- The ARexx extention 

del [the address of the ARexx task] 

del [the address of rexxsyslib base] 

del [the rm_Action field] 

del [the rajlesultl field] 

del [the ta~Eesult2 field] 

ds.l lo ;~ Axgs r it addresses for upco 16 RexxArg strings 

del [the address of your program's public port] 

del [the address of your port's naite string] 

del [an ascii null-terminated string to he appended to script names] 

del [standard input handle] 

del [standard output handle] 

del [the ra avail field] 



How does an ARexx script tell ARexx to direct RexxMsgs 
to your program? It does so with the ARexx command: 

ADDRESS portname 

where portname is the name of your program's public 
port. For example, if your program adds a port named, 
'myPort', then an ARexx script can cause RexxMsgs to be sent 
there with the line 

ADDRESS 'myPort' 

This is case-sensitive, so the ARexx script must exactly 
match the name of your program's port. 
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When does ARexx send a message to your program? It 
does so whenever it encounters a iine in an ARexx script which 
does not contain one of ARexx's built-in commands. For 
example, if an ARexx script contained the following line: 

SAY 'hello' 

then ARexx would print the word hello to the CLI window. 
SAY is a built-in ARexx command so it would be handled 
entirely by ARexx. There is no need to send an ARexx message 
to your program. On the other hand, assume that there is this 
line in a script: 

'BLORT' 'hello' 10 

Note that 'BLORT' is not flush against the left margin (i.e. 
there are some leading spaces at the beginning of the line). 
Because of this, ARexx does not interpret it as a variable, but 
rather as some command (since it is the first element). Also 
note that I quoted 'BLORT'. Although this is not necessary, it 
ensures that ARexx sees it as a command, just in case there also 
happens to be a variable by the same name earlier in the script. 
ARexx determines that it has no built-in command 'BLORT', so 
it packs up this entire line in a RexxMsg and passes the 
RexxMsg to your public port. The line is sent as a null- 
terminated string with the address stored in the first rm_Args 
field of the RexxMsg (at an offset of 40 bytes). When your 
program gets the RexxMsg from the port (via Exec's GetMsg) 
and gets the address in the first rm Args field, this is the string 
that you find at this address: 

BLORT hello 10 

Note that the command and the two arguments, hello and 
10, are all passed in one string. Also note that although the 10 
in the ARexx script was not placed in quotes, ARexx sends it as 
an ASCII string nevertheless. It is up to your program to parse 
this string, separating the command from its arguments, and 
convert any numeric argument (the '10' in this example) to a 
real value. Then, your program analyzes the command, and 
does something based upon it, perhaps using the arguments. 
(Your program better know what to do when it receives the 
'BLORT' command.) Note that the command and arguments 
may be separated by one or more spaces, but all quotes are 
removed from around string arguments. Unfortunately, this 
makes it possible to misinterpret a string with imbedded 
spaces as several arguments. If, for example, a user wanted the 
second arg to be 'hello world', the best approach would be to 
use this line in the script: 



'BLORT' 



"hello world" 



10 



Then, the RexxMsg' s rm_Args string would be 

BLORT "hello world" 10 

ARexx removes the single quotes around the '"hello 
world'", but leaves the imbedded double quotes which your 
program can use to isolate the single, string arg. You'll 
probably encounter several problems with respect to the 
confusing and unpredictable manner in which ARexx treats 
single quotes and whitespace. 

Let's assume that our program uses the 'BLORT' com- 
mand to mean "open a window, print the first argument in a 
window, DOS Delay( ) for the second argument, then close the 
window." When we received this RexxMsg, we would detect 
'BLORT' as the command, open a window, print "hello", 
Delay ( ) for a factor of 10, then close the window. 

After your program handles the RexxMsg, you must set 
up the two rm_Result fields, and reply it via Exec's ReplyMsg. 
The rm_Resultl field should always be if there were no 
errors in handling the RexxMsg. If there was some problem 
(for example, we couldn't open our BLORT window), then this 
should be set to an error severity level (i.e. not 0). A good 
guideline is 5 for warnings, 10 for errors, and 20 for fatal 
errors. The rm_Result2 is used for passing any strings back to 
the ARexx script. If you have no string to send back, then set 
rm Jlesult2 = 0. Otherwise, it is the address of some RexxArg 
string (to be discussed shortly). This is useful for commands 
where you might need to return some data to the ARexx script. 
Note that if you set rm^Resultl to some error (not 0), then you 
should always set rm_Result2 to 0. Do not return a RexxArg 
string when an error occurs. Also, you should not return a 
RexxArg if the rm_Action's RESULT bit is not set. We'll 
discuss rm_Action later. A script must have the following line 
if it wants you to send back a RexxArg: 

Option Results 

Note that your program receives a RexxMsg for every 
individual line in the ARexx script that has a command which is 
not one of ARexx's built-in commands. Therefore, your 
program can receive numerous RexxMsgs per script. Each 
RexxMsg is just one "step" of the script (i.e. one command and 
any arguments for it). ARexx sends these "unknown" com- 
mands to the port identified with the last ADDRESS command. 
If an ARexx script has several ADDRESS commands, ARexx 
sends messages to the portname of the last encountered 
ADDRESS command. This is so that different parts of an 
ARexx script can send messages to different applications. The 
ADDRESS command can even be placed before each line of the 
script to ensure which program that line is sent to. For ex- 
ample, if your portname is 'my Port', then this would ensure 
that your program gets that 'BLORT' command: 

ADDRESS 'myPort' 'BLORT' 'hello' 10 
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ARexx normally passes RexxArg strings. For example, that 
command string in the first rm_Args field is really a RexxArg, 
A RexxArg looks just like a normal null-terminated string, 
except that it has eight bytes PREPENDED to it; i.e., at a 
negative offset from the address that ARexx gives you. These 
prepended bytes contain info about the total length of the 
string (not counting the end null byte), some flags for ARexx's 
use, and the total size of the RexxArg, Let's see what our 
'BLORT' RexxArg really looks like: RexxArg: 

del 23 

;the total size of this particular RexxArg 
dew 14 

;the length of the string 
dc.b [ARexx's flags] 

dc.b [ARexx's hash count for the string] myStr 
dc.b 'BLORT hello 10', 

So, the address in the RexxMsg's rm_Args field would be 
the label myStr, not RexxArg. If you wanted to find the length 
of the string, you would grab the word at an offset of -4 from 
this address. 

How Your Program Controls ARexx 

Your program can cause ARexx to load and execute some 
ARexx script. This script could then send RexxMsgs to another 
program, or even your program, like a macro key or self- 
running demo. To do this, you must allocate a RexxMsg, set 
the rm_Action and rm_Args fields, store your port's address in 
the MN_REPLYPORT and rm_Passport fields, store the port's 
name in the MN_NAME and rm_CommAddr fields, optionally 
set up the rm_FileExt, rm_Stdin, and rm_Stdout fields, and 
send this RexxMsg to the ARexx server's public port which is 
named 'REXX'. You send the RexxMsg by using Exec's 
FindPort to locate the address of the 'REXX' port, then use 
Exec's PutMsg. 

Since the ARexx server is a library, your program can 
open it and call functions that allocate and free RexxMsgs. This 
is probably the best approach since ARexx then takes care of 
most of the setup of the RexxMsg, and freeing of resources. 
ARexx's CreateRexxMsg allocates a RexxMsg and sets up all 
fields to default values (usually 0). Then, you only need to set 
the rm_Action and rm Args yourself. 

Normally, you set the first rm_Args field to the address of 
a RexxArg string. (You can create this RexxArg using the 
ARexx library's CreateArgstring.) This string is the name of the 
ARexx script file that you want ARexx to load and execute. In 
addition, you may supply an extension in the RexxMsg's 
rm_FileExt field if desired. This will be appended to the 
filename. The rm_Action field (a long) contains certain 
subfields. The high byte of this long is a command field. You'll 
set it to RXCOMM (1) to indicate that this is a command level 
invocation. It may be set to other values instead if you wanted 
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to add/remove function libraries, hosts, or open/close the 
trace console. Normally, you don't need to do these things 
from a program so this article will skip those topics. 

For RXCOMM, ARexx will load and execute the entire 
script, firing off RexxMsgs to other applications as need be. 
When all of ARexx's RexxMsgs are returned and the script is 
complete, ARexx returns your initial RexxMsg to your public 
port. The rm_ResuItl field will be if there were no errors. 
Otherwise, this field will be an error severity level. The 
rm_Result2 field will be some RexxArg string that was sent 
back to you from either ARexx or another application; 
i.e.,maybe you're expecting some data back. Your program 
should then free all rm_Arg RexxArgs and the RexxMsg (via 
ARexx library's DeleteArgstring and DeleteRexxMsg func- 
tions). 

There are a few other features you can utilize by setting 
bits in the rm_Action field before sending off the initial 
RexxMsg. These bits are set in conjunction with rm_Action's 
high byte = RXCOMM. For example, you can set the TOKEN 
bit (19). This will cause ARexx to parse and separate each 
argument of the script line, and create separate RexxArgs for 
each. 
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Let's assume that we have the following two lines: 

number =400 
'BLORT' 'hello world' 'hi' number 

ARexx will separate 'BLORT' into one RexxArg, storing the 
address in the first rm_Args field (at an offset of 40). Then, 
'hello world' will be separated into one RexxArg with the 
address stored in the second rm_Args field (at an offset of 44). 
This solves the problem of imbedded spaces in arguments 
since ARexx is doing the parsing for you. 'hi' will be the third 
rm_Args string. The fourth rm_Args string will be the value of 
the variable "number". Since number was assigned equal to 
400, ARexx substitutes this before parsing to produce a fourth 
rm_Arg string of '400'. The lowest nibble of the rm^Action 
field will be set to the number of arguments. In this example, 
that's 3. (A RexxMsg can hold up to 15 tokenized arguments 
since it has 16 rm_Args fields. The first rm_Arg field is always 
reserved for the command.) The one problem with setting up 
your ARexx implementation to expect tokenized arguments is 
that the user may write and invoke a script that doesn't 
tokenize — the more common scenario. Of course, you can 
always check the rm_Action's nibble to see if any arguments 
were tokenized, or if you have to parse, args from the one 
rm_Args string yourself;(i.e., rm_Action's low nibble = 0). 

If you set the RESULT bit (17) of rm_Action, this means 
that you allow ARexx (or some other application) to return a 
RexxArg in the RexxMsg's rm_Result2 field. You MUST set 
this bit if you expect some returned string there. Otherwise, no 
one else should ever return a RexxArg to you. You are respon- 
sible for freeing any returned RexxArg even though you may 
not have allocated it. 

If you set the NONRET bit (20), then this means that you 
don't want ARexx to ever return your RexxMsg. ARexx will 
free the RexxMsg and all allocated RexxArgs on your behalf. 
Of course, this means that you'll never know if the RexxMsg 
was handled successfully since you won't be able to examine 
the returned rmResultl field. Also, you can't get any returned 
RexxArg in the rm_Result2 field. 

The NOIO bit (16) causes ARexx to suppress its rm_Stdin 
and rm_Stdout. This can be used to prevent ARexx from 
printing messages to the CLI window. This may have to be 
done if your program is run from Workbench and has no 
default tool window. ARexx is not too intelligent about 
recognizing whether a host program was CLI or Workbench 
launched, and may even crash from Workbench. 

If you set the STRING bit (18) of rm_Action, this means 
that the first rm_Arg is not the name of some ARexx script to 
invoke, but instead a complete script to execute. In other 
words, you can directly pass an entire ARexx script to ARexx 
by placing the address of the ASCII script in the first rm_Args 
field, setting the STRING bit of rm_Action, and sending the 
RexxMsg to ARexx. Each line of the script must be separated 
by a semi-colon or newline. This is useful, for example, if your 



program has a set of macro keys. You could allow the user to 
write and bind an ARexx script to each macro key. Then, 
instead of requiring ARexx to access some disk in order to load 
a script, you can pass the script directly, eliminating any disk 
swapping by the user or load delays. 

If your program both accepts RexxMsgs from ARexx and 
also can create and send RexxMsgs to ARexx, you can use one 
public port provided that you can recognize whether a 
RexxMsg queued there is a reply to one that you created, or 
simply one that ARexx wants you to implement. The best way 
to tell is to examine the RexxMsg's MN_REPLYPORT (at an 
offset of 14) to see if it is the same address as your port. If so, 
this is your own RexxMsg being returned and you must free it 
now. If not, then some ARexx script has just sent a command 
to your program and expects you to handle it, then reply the 
RexxMsg. 

Alternately, you might want to add two public ports, 
having one for ARexx scripts to ADDRESS to, and the other for 
your program to get back RexxMsgs that you create and send 
to ARexx. Note that you should NEVER alter the rm_Args, 
rm_Action, or most other fields of RexxMsgs that are sent to 
you from ARexx. In this case, you are only allowed to modify 
the rm_ResuIt fields. 

WARNING: The ARexx server stomps all over structures 
which are not its own. It may alter fields of your task control 
block, and will definitely alter fields in a RexxMsg that you 
send it while the message is in its possession. (For example, 
ARexx alters your MN_REPLYPORT field while using the 
RexxMsg). 

AN EXAMPLE 

Now that you know how ARexx works, and how your 
program communicates with it, I'd like to introduce my own 
rexxapp library. This library makes adding an ARexx imple- 
mentation to any program very easy. It helps you setup a 
unique public port that you can Wait( ) for RexxMsgs to arrive 
at. It takes care of allocating and freeing ail RexxMsgs and 
RexxArgs. It also deciphers whether a RexxMsg is one that you 
sent out, or one sent from ARexx. For ones that you sent out, it 
determines whether the result was an error or success, and 
calls one of two routines in your program accordingly. For 
ones sent from ARexx, it checks a "list" of your program's 
recognized commands against the received command. If 
found, it calls a "dispatch" routine in your program, passing 
the address of the function that you've attached to that 
command. It takes care of replying RexxMsgs. It also has a 
routine to close your port down. In short, it completely 
manages almost all of the ARexx details on your behalf via just 
a half-dozen, easy-to-use functions. The only thing that your 
program needs is a special data structure for the library, a list 
of your command strings (along with the addresses of func- 
tions that are associated with those commands), and the actual 
functions. 
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To demonstrate how to add an ARexx implementation 
(using my rexxapp library), I'm going to take an existing 
program and add the extra ARexx code. The program that I've 
chosen is an assembly listing that appears in a series of 
previous Amazing Computing articles which I wrote. I chose this 
program because it has several features that can be controlled 
over ARexx. Therefore, I can add an ARexx implementation 
with several commands. Also, since the text of those articles 
appears on this disk, you can get a detailed description of that 
program by reading the file, "Paint.txt", and this article can 
concentrate solely on the ARexx code. Read "Paint.txt" now, 
and study the original source. 

The first step in adding an ARexx implementation is to 
decide upon the name of your public port. I'll choose 'Painf . 

The next step is to decide what features of the program 
you wish to be accessible over ARexx. For example, my Paint 
program allows the user to select one of three pen numbers for 
the drawing color. Let's allow this to be done over ARexx. We 
need to decide upon some command string. I'll arbitrarily 
choose 'COLOR' for this command. Furthermore, I'll expect 
one argument — the pen number. So maybe the following line 
will appear in an ARexx script: 

ADDRESS 'Paint' 'COLOR' 1 

ARexx will send a RexxMsg to my Paint port with the first 
rm^Args field being a RexxArg string as so: 

COLOR 1 

The rexxapp library will look through my list of commands, 
find the 'COLOR' command, and call its associated function (to 
set the drawing pen), passing the argument T. My function 
will then set the pen to 1. 

For my Paint program, I'll also have the commands, 
TOFRONT' and TOBACK' to move the window to the front 
and back respectively. The 'QUIT' command will cause the 
program to exit. The 'LINE' command will draw a line 
between two points. This command will take 4 arguments: the 
x start position, y start position, x end position, and y end 
position. The 'BOX' command will draw a filled rectangle. It 
has 4 arguments: left x position, top y position, right x position, 
bottom y position. 

Finally, the 'VERSION' command will cause the Paint 
program to return a RexxArg string to the script. The string 
will be the title of my program. Note that my script must have 
OPTION RESULTS for this to work. ('VERSION' is the only 
one of my commands that returns a RexxArg string. The others 
do not.) 

Now that I've decided upon the ARexx commands that 
my program understands,taking care not to name a command 
the same as one of ARexx's built-in commands, I'm ready to 
add code to my program. 



1 need to write a function that implements each command. 
For example, I wrote rexxtofront to be called whenever I 
receive the TOFRONT' command. The function rexxline is 
called whenever I receive the 'LINE' command. If you've 
written your code with ARexx in mind, features that can be 
accessed both by the user and over ARexx can often share the 
same code. RexxPaint.asm is my program with the ARexx 
implementation added. 

Now, let's examine how the rexxapp.library works. Make 
sure that this file is copied to your LIBS: drawer. 

This library operates upon what I call a RexxData struc- 
ture. There is an instance of this at the label, _rexxPort. This 
structure has an imbedded port that I'll use for ARexx commu- 
nication, plus various other fields as described. It also has what 
1 call an association list. This is a series of LONGS. The first 
long is the address of one of my ARexx commands, and the 
next long is the address of the function associated with that 
command. This is used by rexxapp lib to determine if a 
received RexxMsg has a command that my program handles, 
and if so, what routine is to be executed as a result of receiving 
that command. 

When a match is found, the lib will call a function in my 
program called my Dispatch, passing the address of the 
received RexxMsg, the string containing any arguments, and 
the address of the function which is associated with that 
command. It is up to myDispatch to do any initial setup if 
needed, call that function, and setup the RexxMsg Result fields 
upon return. There is a doc file for using the rexxapp.library 
called "RexxAppLib.doc". You should read that now. 

First, I need to open the rexxapp.library and set up my 
port, named 'Paint'. Since this is only done once, I added the 
call to the openjibs routine at label RX1. 1 store the lib base 
address at j-exxBase. At RX2, 1 put the base of my RexxData 
structure in a5. All of the rexxapp lib routines require that this 
structure's address be in a5. The lib function SetRexxPort 
completely sets up the port. After this call, I'm ready to receive 
or send RexxMsgs. Note that my RXname has an extra null 
byte at the end. The reason is that the lib resolves any port 
name collisions by appending a number to the name. The first 
copy of my program adds a port called 'Paint'. If I run a second 
copy of the program, its port name is 'Paint2'. If there's an 
error setting up the port, SetRexxPort will set the z-flag and 
return an error message in aO. I simply print that message to 
my window. 

It's always safe to call any other rexxapp lib routine even 
if the port is not setup. In this case, the lib routines will do 
nothing. 

Now, in my main IDCMP loop, I have to Wait( ) on both 
my Intuition window port AND my ARexx port. At RX7, 1 do 
this by creating a mask of both the Intuition port's SigBit and 
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the mask that rexxapp lib made for me when I called 
SetRexxPort. This mask is in my RexxData structure (at the 
label RexxMask). 

At RX6, I've added a call to ReceiveRexx. This is the lib 
function that will handle any received RexxMsgs by calling my 
dispatch function. It also handles any returned RexxMsgs that I 
sent to ARexx, calling my ErrorVector (printRexxErr) or 
ResuItVector (doResult) depending upon whether there was an 
error or successful result respectively. It handles all RexxMsgs 
that are currently queued at the port. When there are no 
messages at the port, it returns. 

Note that when I wake up from Wait( ) at label E6, 1 could 
add code to check the mask in dO to see whether I woke up 
because of an IntuiMessage and/or a RexxMsg received. Then 
I could choose whether to GetMsg{ ), or ReceiveRexx( ), or 
both. Instead, I just check both ports anyway because this 
doesn't take too much time. 

Let's assume that some ARexx script is ADDRESSing our 
port. When I call ReceiveRexx, this causes the library to call 
myDispatch. First, I clear a few variables. Then, I save my 
window's current PenA setting, and change it to the last value 
used with ARexx, stored at rexxPenA. This is just so that if I 
receive an ARexx 'COLOR' command, this doesn't change the 
user's Pen choice too. Note that I can find a window's current 
PenA value by getting it from the RastPort. Next, I call the 
vector that the lib passed me. This will be one of my ARexx 
handlers depending upon which command was received. Let's 
assume that the command was 'LINE 10 10 20 30', so I'm 
calling rexxline. 

In rexxline, I need to parse the command line for 4 
additional numeric args. The lib has passed me the '10 10 20 30' 
part of the command line. I call GetBoxCoords to parse those 4 
args, convert them to actual values, stuff them into some 
variables, and do some error checking that the values make 
sense and are within my window borders. I Move( ) to the 
location specified by the first 2 args, and Draw( ) to the 
location specified by the last 2 args. This renders a line in the 
color of rexxPenA. 

Upon return to myDispatch, I restore the PenA to what the 
user selected. Then, I setup the RexxMsgs rm_Resultl and 
rm_Result2 fields via SetupResults. Note that if 1 encountered 
some error, I set the variable error to some non-zero value. 
This prompts me to return a secondary error in dl of 10 
instead of 0. If I had a Result string to return, I stored the 
address in ResultString. (rexxversion is my only handler that 
returns a result string.) If there's an error, the library won't 
send the result string anyway. Note that after calling 
SetupResults, I can dispose of my result string if desired. 



Remember that each call to myDispatch represents only 
one command of an ARexx script;(one receipt of a RexxMsg) 
It's entirely possible that the user may be operating some part 
of the programme., Intuition messages are being sent simulta- 
neously. This could result in main alternating between 
handling a RexxMsg and an IntuiMsg. A good example of this 
is to execute the ARexx script, DrawLines. While the script is 
executing — drawing a series of lines in the window — note 
that you can be drawing with the mouse. It almost appears as 
if two separate processes are operating on the window. In fact, 
two processes are simultaneously sending messages to my 
ports: Intuition and ARexx. Of course, my program is handling 
each as it arrives. Because of this, it may be necessary to keep 
separate variables for ARexx and Intuition's use such as I did 
with the PenA value, and change/restore parameters within 
the dispatch routine. Otherwise, the user's actions might 
disrupt an executing ARexx script and vice versa. 

I've added the facility to invoke an ARexx script from my 
program. If the user types a script name in my window string 
gadget, I'll send this to ARexx. I do this in the gadget_up 
routine, when the user finishes using the string gadget. At U2, 
I call the rexxapp lib function, ASyncRexxCmd, passing the 
user entered text in aO (StrBuffer). This function allocates and 
sets up a RexxMsg, creates a RexxArg based upon the contents 
of StrBuffer, and sends the message to ARexx. Upon return, the 
z-flag is set if an error, and an error message is in aO. Note that 
I can now change the contents of StrBuffer if desired. An 
important thing to note is that ARexx may not even have 
started the script when ASyncRexxCmd returns. My program 
is simply telling ARexx to invoke the script, and returns even 
while ARexx is loading and proceeding to execute that script. 
For example, you can execute the DrawLines script by typing 
its complete path in the Paint window's string gadget and 
pressing return. This is an example of a program invoking a 
script which controls itself. Make sure that the ARexx server is 
started via RexxMast! 

Finally, I demonstrate how you can send a string file 
(instead of a script invocation) to ARexx. I added a new 
"ARexx" menu item to the Project menu. When this is selected, 
I send a small, string file that 1 constructed at the label 
myStringFile. Note that this doesn't have to be a RexxArg 
structure, but should be null-terminated. Also, both the 
RXCOMM and RXSTRING bits are set. This string file just 
draws a small rectangle in the upper left window corner. 

When the program exits, I have to remove my port and 
close the rexxapp library. This is done in the quit_all routine at 
the label RX5. 
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Adding 
Help to 
Applications 

Easily 

Implement an 'on-line help 
facility in your applications using 
this powerful, yet easy-to-use, 
arsenal of functions... 
fust call helpi )! 



Since the Amiga's introduction, a key labelled "Help" has 
been prominently displayed on the keyboard. However, very 
few applications make use of the key. Of course, there are 
many other ways to allow the user to request help; a help 
menu or gadget are two mechanisms that quickly come to 
mind. 

Although the Help key is easy for a user to access, perhaps 
it has been inconvenient for programmers to integrate into 
code. Applications that use VANILLAKEY instead of 
RAWKEY don't get IDCMP messages when the user presses 
the Help key. However, it is strongly suggested that effort be 
taken by Amiga programmers to provide some means for the 
user to get "on-line" help from applications. For this very 
reason, the following arsenal of functions has been written; 
these functions are invoked behind the scenes when an 
application makes a simple call to help( ). 

The major goals set for the design were: 

1) It shall be easily invoked by applications. 

2) All help text shall be in a file separate from the application 
and should not require anything to be recompiled when 
the help text changes. This allows for last minute editing 
of the help file without impacting the application code 
itself. There cannot be any side effects in the application 
due to editing the help text file. Also, by having a separate 
file for help text, the application code can be made 
language independent (English, French, etc.). In fact, the 
application can use "help text" files to determine the 
strings for Intuition menus, gadgets, etc. 

3) The application can specify which font the help text is to 
be displayed in. The help facility must work with ANY 
font, including proportionally spaced ones. 
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"It is strongly suggested that effort be taken by 
Amiga programmers to provide some means for the 
user to get 'on-line' help from applications." 



4) The help text file(s) shall be keyed, so that the application 
would request help for a certain string or topic and the 
help facility will automatically display the appropriate 
text. 

5) Neither the application nor the help text file itself are to be 
bothered about formatting the help messages. Word wrap 
shall happen automatically, based on font and window 



6) Different type styles, drawing modes, and text colors shall 
be easily specified by the author of the help text file. 

7) The help text file can specify the location and size of the 
window for each help text entry. 

It is believed that all of the above goals have been met, 
and I would encourage readers to examine the code, use it, 
modify it, and/or learn from it. At the end of this article, other 
uses for the code and possible future enhancements to it will 
be described. 

The help utility was written and compiled using Manx 
Aztec C 3.6a. It was written to be compiler non-specific (except 
for compiler-specific header files), but it has not yet been 
verified that the code will compile using any other compiler. 

Design Overview 

The design was started by identifying the above goals and 
then deciding how help text files should look, how the user 
interface should work, and how the application should invoke 
the help facility. Each will be quickly described below. 

Format of Help Text Files 

The help text files are ASCII files. They are composed of 
key lines and help text. An example of a help text file is shown 
in Listing One. Key lines start with the '©' character, which is 
immediately followed (no intervening spaces) by a key string. 
Following the key string is another '©' and then an optional set 



of values used to specify the location, size, and sizing limits of 
the window that will display the help text. Default values for 
the window will be used for any of the above that are not 
specified by the key line. 

Following the key line are the lines of text that are to be 
displayed when the application requests help for the key in the 
associated key line. These lines of text may contain special 
escape sequences that allow the author of the file to specify 
drawing mode (J AMI, JAM2, COMPLEMENT), text style 
(italics, bold, underlined, plain) and front and back pen colors. 
Because word wrap occurs automatically, and extra white 
space is normally stripped out, an escape sequence to force a 
space into the help display is provided. Another escape 
sequence forces a new line to occur. Table One lists the 
available escape sequences. The two character sequence '\©' is 
used to indicate the end of each help text message. 

The User Interface 

When the help facility is invoked, the user will be pre- 
sented with a window containing the help text. If there is more 
help text than will fit in the window at one time, the user can 
scroll through the text using the mouse and a proportional 
gadget or with the cursor keys. Table Two lists the usage of the 
cursor keys alone as well as with the SHIFT and ALT qualifi- 
ers. It was felt that the user should be able to completely access 
the features of the help facility from the keyboard as well as 
from the mouse since some applications, such as text editors, 
may be keyboard intensive. The user can resize the help 
window within the limits specified by the key line for the 
message; the key line can also prevent the user from resizing 
the window. 

The Application Interface 

Aside from opening intuition.library and graphics.Iibrary, 
the only things the application needs to do is open the help text 
file for read access and call help( ) with the correct values for 
its four arguments: the file pointer; a pointer to the screen 
where the help window should open (or NULL if the help 
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Table One 


Escape Sequences Available 


\B 

\b 


Bold on 
Bold off 


\U 


Underline on 
Underline off 


\l 

\i 


Italics on 
Italics off 


\N 


Bold off. Underline off. Italics off 


\J1 
\J2 
\X 


JAM1 Drawing Mode 
JAM2 Drawing Mode 
COMPLE MENT (XOR) Drawing Mode 


\On 


Color number to use for the Front Pen 

(n can range from to the 

maximum number of colors in your palette). 


\Rn 


Color number to use for the Back Pen. 
(\B was already used — \R 
was chosen for "Rear Pen"). 


\s 


This will cause a space to be displayed without 
allowing the token to be split across two lines. 
This wilt allow for uses like PAsSAsKasten — 
the entire name will be treated as a single 
token, Multiple spaces can be forced (\s\s\s will 
create three spaces). 


\\ 


Use this to put a backslash in your help message. 


\n 


This will force a new line. 


\@ 


This indicates the end of a message. 



Table Two 

Cursor Keys 



The keyboard, as well as the mouse, con be used to scroll 
Ihrough help messages. 

Up Scroll up one line 

Down Scroll down one line 

Shift-Up Scroll up one page 

Shift-Down Scroll down one page 

Alt-Up Go to the first page of the message 

Alt-Down Go to the last page of the message 

In addition, the ESC key can be used to close the help window. 



window is to open on the WorkBench screen); a pointer to the 
null-terminated string to be used as the key and a pointer to 
the TextFont structure used to display the help text (or NULL 
if the default RastPort font is to be used). If a font is specified, 
it must already be opened by the application. Once called, the 
help( ) function won't return to the application until the user 
has closed the help window. 

As can be seen from the above descriptions, all three 
"interfaces" are simple to use. Once the look and feel of the 
design was chosen, the actual algorithm design took place. The 
design was broken into three main steps: 

1) Locate the text for the specified key. 

2) Read all the help text into a set of data structures that 
accounts for window size and text styles. 

3) Present the user with the formatted text. 



The second step is really the workhorse of the project and 
is broken down into many smaller steps and, therefore, 
functions. Since each of these functions needed access to 
similar information, a Helplnstance data structure was created. 
A pointer to this structure is passed to all the functions. This 
allowed the avoidance of global variables, and kept all the 
control data in one place. The next few sections will describe 
the three major steps in greater detail. However, to gain a 
complete understanding of the project, the reader is referred to 
the heavily commented source code. 

Locating the Key String/Help Message 

The format of the help text files greatly simplifies the 
search for the correct help text. Entire lines are read in one at a 
time. If the line that is read doesn't start with '©', the line is 
discarded and the search continues. If a line is found that starts 
with '©', the next characters are compared with the key string. 
If a match is found, this line is the key line and all subsequent 
lines {until a special delimiter, or the end of the file, is found) 
become the text that will be displayed to the user. The special 
delimiter is the two character sequence '\@'. If the end of the 
file is reached before a match is found, the screen will flash and 
help( ) will return. 

A design decision was made to claim that a match is 
found if the specified key matches the beginning (but not 
necessarily the entire) string on the key line. For example, if the 
help text file contained a key line that read: 

@FunctionKeys@ 

and helpt ) was invoked as in: 

helplfile, NULL, "Fun", NULL) 
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Then a match would be considered to have been found. This 
design decision was made anticipating applications which 
allow the user to specify the desired key string — the user only 
has to type in enough characters to get the unique help text 
entry. However, note also that the comparison is case sensitive. 
It is quite easy for an application and help text file author to 
create a case-insensitive environment for the user. 

The key line can contain (optional) window values. The 
complete format of the key line is: 

8 key string91eft/top/width/height/r,i[i_width/mIn_height/max_widtli/maK_hsight 

Note that a '©' character is required between the key 
string and the window values. The key string may contain any 
printable characters (including spaces) except for the '&. 

The length of the entire key line cannot exceed 80 charac- 
ters. Default values will be used if the window values are not 
specified. The window values must be specified in the order 
shown, but not all need to be specified. If it is desired that the 
default minimum and maximum values for window size be 
used, those values need not be placed on the key line. How- 
ever, a value cannot be skipped; i.e., if the programmer needs 
to specify the left edge and the width of the window, the top 
value must be specified. For those cases, placing a value of -1 
in the location for the value you don't want to specify will 
cause the default value to be used. Default values for the 
window specifications are shown in Table Three. Note that the 
key string will become the title of the help window. 

Comments (text that will never be displayed by the help 
utility) can be placed in the help text at the beginning of the 
help text file, at the end of the file, and between messages in 
the file. Listing one illustrates the use of comments in help text 
files. 

Reading and Processing the Help Text 

Once the key string has been located and the window 
specifications determined, the help window is opened on the 
screen specified by the application. Next, a data structure 
named Helplnstance is allocated and initialized. 

The Helplnstance data structure is a repository for 
"global" information. For example, it holds pointers to the help 
window, screen and font, and values of window size, drawing 
mode, pen colors and softstyle. It also keeps track of line 
indexes and buffers for token processing. Other values stored 
in the Helplnstance data structure are as follows: the number 
of pixels that can be in one line of help text (calculated from the 
window width), the number of pixels used in the current line, 
the number of characters in the current token, the total number 
of help lines in the help message, the line number of the top 
line displayed in the window, the number of help lines 
displayable in the window (based on font height and window 
height), some flags, and an Intuition RememberKey. Using the 



Table Three 


Default Window Values 


Top: 
Left: 


20 



Height: 


custom screen height/2 or 
GfxBase->NormalDisplayRows/2 


Width: 


custom screen width or 
GfxBase-> Normal DisplayColu mns 


Min Height: 
Min Width: 


The above value for Height 
The above value for Width 


Max Height: 
Max Width: 


-1 (maximum window height) 
-1 (maximum window width) 


In addition, the window title will be the key string, as specified by 
the help text file. 



Helplnstance data structure eliminated the need to use global 
variables. A pointer to this data structure is passed to every 
function comprising the help facility. 

The general approach taken to process the help text is as 
follows. The number of lines of text that can fit within the help 
window, as well as the number of pixels in a line, are calcu- 
lated from the window size and font size. The help text is built 
one line at a time, each line being composed of one or more 
segments. A segment is a piece of text that is to be displayed in 
a single drawing mode, pen color and softstyle (from here on, 
these three characteristics will be called the text style), A 
segment is composed of one or more tokens. A token is usually 
a word (a string of characters delimited by white space in the 
help file). However, if a "word" in the help file is made up of 
multiple text styles, or if the word is larger than the size of the 
buffer used for tokens, the word will be broken into multiple 
tokens. The entire help file is read in and processed before the 
help text is displayed in the window. 

A line is simply a linked list of segment structures 
(HelpSegmentStruct). A line index (HelpLinelndexStruct) is 
used to point to the first segment of each line. Line indexes are 
fixed in size; if there are a greater number of lines in the help 
text than can be kept track of in a single line index, additional 
line indexes will be allocated. Line indexes are linked together 
such that the line to be displayed after the last line in index N 
is the first line in index N+l. Figure One should greatly clarify 
how all the data structures fit together. 

During the course of reading and processing the help text, 
many data structures are allocated. The Intuition 
RememberKey facility is used to track all memory allocated 
except for the memory allocated for the Helplnstance data 
structure. 
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>ince you are dedicated to 

mastering your Amiga and using it 

to its fullest potential — be sure to 

maximize your possibilities 

when it comes to required reading, too! 

That is easily accomplished by 

subscribing to the "Amazing" family of 

high-quality AC publications, including 

the original monthly Amiga magazine, 

the only complete Amiga product guide, 

and now, the first disk-based, 

all-technical Amiga publication! 

Amazing Computing. 

ACs GUIDE. 

ACs TECH. 

When you consider the many 

possibilities confronting you today — 

AC publications represent Amazing values 

you simply can't afford to overlook. 



call 1-800-345-3360 

(credit card orders only; please have Visa or Mastercard ready) 



Displaying the Help Text 

Once all the text has been read and processed, it is 
displayed to the user. As mentioned earlier, the user can scroll 
through the text and resize and drag the window. If the 
window width is changed, the help text is read and processed 
again before being displayed. The reason is that the number of 
pixels per line has changed and word wrap will likely need to 
occur in different places. (Because all the segments in a line are 
linked together, it is actually relatively simple to recalculate the 
display without re-reading the file. Perhaps a future version of 
this utility will use such an approach.) 

The line indexes allow for quick updating of the display 
when the user scrolls the text. By processing and formatting 
the text prior to displaying it, very little work needs to be done 
to display the text. 

Using help( ) In Your Applications 

The purpose of this set of functions is to provide a simple, 
consistent method for applications to incorporate context- 
sensitive, on-line help. In order for an application to use these 
routines, the application must do the following: 

1) Open intuition.library. 

2) Open graphics.library. 

3) Open the appropriate help text file for read access. 

4) Call help( ) with the appropriate arguments. A prototype 
of the help call is: 

BOOL help (FILE "helpfile, struct Screen 'screen, 
chat "helpkey, struct TextFant *font) 

If a pointer to a custom screen is given, the screen must 
already be open. NULL can be passed in for the screen 
argument if the help window is to open on the WorkBench 
screen. If a non-NULL pointer to a TextFont structure is 
passed, the font must already be open. Note that help( ) will 
return FALSE if the specified helpkey was not located in the 
helpfile; otherwise, it will return TRUE. It should be obvious 
that there is very little work the application programmer need 
do to use this code in his or her product. 

Caveats 

Of course, this utility cannot be everything for everybody; 
in fact, it wasn't meant to be. It was designed to be both easy to 
use and full of features, but each additional feature increases 
the size and complexity of the tool. As is usually the case, 
certain compromises were made in the design; these compro- 
mises and design decisions are listed below. Of course, any or 
all of these may be addressed by modifying the existing code. 



1 ) Tokens with multiple text styles may be broken across 
lines. For example, a token such as 

"Partially \Uunderlined\u" may end up being displayed 
with the word "Partially" at the end of one line and the 
word "underlined" at the beginning of the next (of course, 
"underlined" will be underlined). A simple way to 
circumvent this problem is to force a line break to occur 
prior to the token ("\nPartially\Uunderlined\u"). 

2) Similarly, long tokens (even of a single text style) may be 
broken across lines. This is relatively unlikely, since with 
the values currently chosen in the source code such a 
token would need to exceed 30 characters. 

3) If a window is so narrow that a token is found that cannot 
fit on its own line, the remainder of the help text (begin- 
ning with that token) will not be displayed. For example, 
suppose the window is 50 pixels wide and a token is 
found that is 60 pixels long. This token cannot fit on an 
otherwise empty line. All help text processed up to this 
token will be displayed; all help text beginning with this 
token through the end of the message will not be dis- 
played. If the window is resized so that the token can fit, 
the help text will be displayed. 

4) Allowing the user to change the width of the help window 
can cause a carefully laid out display to look different than 
planned. 

The bottom line with all these caveats is that the help text 
file should be considered to be part of your application, 
requiring careful designing, testing and debugging. However, 
since no code needs to be recompiled, the turnaround time is 
extremely short. Once you have entered all your text in the 
help text file, start your application and invoke each help 
message. Make sure that the colors are all well chosen, that the 
text lines up as desired, that all the text is displayed, that 
window sizing has no negative effects, etc. 

Future Enhancements 

No software project is ever truly complete. Below are 
some ideas for possible future work: 

1 ) A change in the window's width won't require the help 
text file to be re-read. Since most help messages are short, 
it was felt that it was no real problem to have the message 
re-read. However, since all the text is already processed 
and all the segments are linked together, it is a fairly 
straightforward job to rearrange the segments and tokens 
in place. 
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Helplnstance 




Figure One 

How the Help 
data structures 
'fit together.' 



HelpLlnelndexStruct 



2) If a help file contains many long messages, it would be 
better to be able to immediately locate the position in the 
file where the message begins. This can be done via 
another file, an index file, which would be created by a 
tool run on the help text file. This index file would indicate 
the file position to seek to for each key string in the help 
text file. 

3) Allow for multiple help windows. Perhaps an asynchro- 
nous interface would be nice so that applications can have 
multiple help messages displayed simultaneously. 

4) If enough applications use this facility, perhaps creating 
an Amiga shared library (help.library?) would keep the 
code size overhead low. 

Other Suggestions for Use 

Although it has constantly been referred to as a "help" 
utility, there are many other uses for the code. In fact, by 
simply using the GetHelp command included on disk (the 
rather short listing appears in Listing Two) it is trivial to create 
these applications. Three examples are a phone book, a recipe 
file and a CLI command help utility. All that would need to be 
done would be to create the help text files (for example 
Phone.help, Recipe.help and CLI. help). If these files are placed 
in the S: directory, the following could be done: 



Alias Phone GetHelp S:Phone.help 
Alias Recipe GetHelo S:Recipe,help 
Alias CLIKelp GetHelp S:CLI.help 



Finally, you can get your recipes for pancakes or apple pie 
by typing: 

Recipe pancakes 
Recipe "Apple Pie" 

Notice the quotes surrounding "Apple Pie" in the above 
example; they are needed because of the embedded space in 
the key string. 

The GetHelp command also allows the user to specify a 
font and a size. If a font is specified, the size must also be 
specified. The font name must be the complete name (e.g., 
ruby. font). 

Listing One can be used as a help text file. It is included on 
disk in a file named Listingl. Used in conjunction with the 
GetHelp command, the reader can easily experiment with the 
various features supported by the help utility. 

Conclusion 

It is hoped that many of you will find this useful for your 
own applications. Remember that the software you create is for 
the user; anything that makes the user's experience with your 
product easier is a plus. Requiring the user to search through 
pages of documentation to (re)discover how to perform at least 
the basic functions of your application can be avoided with a 
set of subroutines such as those presented here. 

[SAS/Lattice 5.10 compatible versions of the help listings are 
supplied on the AC's TECH Disk — Ed] 
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Listing One 

Example HELP text file 



It is lonaer than the first one 



\UIt is testing a few 



end yet it was 



♦•'Comments may be placed in the help file at the very beginning, at the 
•••very end and In between messages. They can be in any format, they 
•••don't need to start with any special character, but using asterisks like 
***! have done here makes the consents standout. 

This is the first entry In the helpfile. 

\§ 

GENTRY2G 

This is the second entry in the helpfile 

and it should cover a couple of lines. 

SENTRY 38 

This is the \B\Uthird\u\b entry in the \C2helpfile\Cl , 

of the \Bmore>b interesting features of the tool. 

\e 

This is a comment. It could be used to describe the reason the next help 
text entry would be invoiced by the application, etc. Since these lines are 
between messages, these will never be displayed by the application. (Notice 
that the lines In this comment do not start with any special characters.* 

This is how to display a \\ (backslash). You can easily display 9 symbols, 
too. And \Uwhlle I am at it,\u this is haw you can get Mit to do 
italicizedU letters. 

@£tfTRY50-l/-l/-l/-l/3O0/3v 

Colored text can be created by \C2specifying\Cl the front pen color in JAM1 

node.\F3 

\n\J2The JAM2 graphics rendering mode is also supported. \Jl\n 

There were a couple of \X\I\UrauItiple\Jl 

escape\u sequericesU there! 

\8 

•**The next example shows how to prevent the window* s size from changing. 

@EHTRY6£40/30/G0071007-1/-1/6QO/100 

The "AMlGA\s200Q" string should have a \Xspace\Jl in It, 

treated as a \U\Bsingle token\H. 

\0 

'"The following keyline indicates how to override the default minimum window 
"•'width and height values, leaving the rest of the window values to take on 
'**tbe default ones. Note that the window specified here can be sized too 
•••small Eor one of the tokens rconsulting/developing") . Experiaent to 
'••see what happens when the window is sized too small. 

0KASTECHe-l/-l/~l/-l/5QaOu7-l/-l 

\B\C3KAS\C2TECH\Cl\b Is a software consulting/developing company located in 

Nashua, VsN.H. Its president, \BPhilip 5. Kasten\b, received his Kaster's 

and Bachelor's degrees in Electrical Engineering and Computer Science 

from the Massachusetts Institute Of Technology. Although he develops 

software for many different systems including the IBM PC and UHIX(tm} 

mainframes, he prefers to focus his company's attention on developing tools and 

entertainment software for the \XCommoctore AMIGA\J1 line of personal 

computers /works tat Ions. 

\fi 

***Key strings CAN have spaces! 

8Apple PieG 

Your favorite apple pie recipe can go here* 

\9 

Hong DescriptLon3I00/50/4D0/1^0/2O0/65 

This is a \Blong\b help text snessage. This window can be made both smaller 

and larger, and the message will automatically be rearranged to fit in the 

display. The proportional gadget, can be used 10 scroll throught the 

message, as can the arrow keys* By using the \B\\n\b escape sequence, it is 

easy to force :he display of the message to look a certain way. For 

example, to create a list one would\n 

\s\s\s\s\C2 1]\C1 Use \B\\n\b to terminate the line before the llst.Nn 

\s\s\s\s\C2 21\C1 Use multiple \B\\s\b to indent the list Items if so 

desired. \n 

\s\s\s\s\C2 3!\C1 Terminate each line in the list with \3\\n\b,\n 

\n 

\OABNQTE\N: if a pen color is to be specified to print a number (as in the 

list item numbers above) the pen color digit and the item number dlfit 

\C3MUST\C1 be separated by white space. \n 

\n 

Also, remember that it is important to make sure that resizing the help 

text window to any size allowed by the specifications in the key line does 

not cause any of the help text to be displayed improperly. If it Is 

desired to not allow window sizing at all, have the key line specify the 

same values for the height, min height and max height as well as for the width, 

min width and &ax width, 

\3 



Listing Two 

GetHelp.c 



• GetHelp.c 

• This is a general purpose wrapper for the help utility. It can be 

• Invoked in two ways: 

• Getfielp helpfile helpfcey 

• GetKelp helpfile helpkey font fontsize 

• To create using Manx Aztec C (3-6a): 

• cc GetHelp.c 

• cc help. c 

• In -o GetHelp GetHelp.o help.o -lc 
*/ 

■include <exec/types.h> 
linclude <stdio.h> 
((include <graphics/text-h> 

struct IntuitionBase *IntuitionBase; 
struct GfxBase 'GfxBase; 
struct Library 'DiskfontBase; 
struct Library 'OpenLibrary l) ; 
struct TextFont *CpenDiskFont f I ; 

extern BOOL heipll; 

mainUrac, argv) 
int argc; 
char "argvjj; 
I 

FILE "file; 

struct TextFont 'font - NULL; 

struct TextAttr attr; 

Int rc=20; 

if (SUargc —31 II large ™ 5)1) exiUrcl; 

if (i(file= fopen(argv[l], "r")M exittrO; 

IntuitlonBase = {struct IntuitionBase *| 

OpenLibrary ("intuition. library", OL) ; 
GfxBase = (struct GfxBase ' JOpenLibrary ("graphics .library'", OL} ; 
DiskfontBase = OpenLibrary ("diskfont. library", OL); 

if (IntuitionBase fr£ GfxBase 6S DiskfontBase) I 

re = 0; 

if (argc — 5) { 



attr.tajlame - (STRPTR>argv[3] ; 
attr.ta YSize - atoi (argv[4] ) ; 
attr.ta"~5tyle ■ FSJtORHAL; 
attr.ta^Flags - fpf_diskfont: 
font ■ OpenDiskFontUattr); 



if (helpffile^ NULL, argv|25, fontl — FALSE! re - 10; 

if (font) CloseFont(font); 

1 

if {DiskfontBase) CloseLlbrary (DiskfontBase! ; 

if (GfxBase) CloseLlbrary (GfxBase} ; 

if (IntuitionBase) CloseLlbrary (IntuitionBase} ; 

fclose(file) ; 
exit Ire) ; 
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Listing Three 

Help.c 



Help Utility For C Applications, copyright 1&91 Philip S. Kasten 

The source code ir. this file is freely iistributable and nay be 
used in commercial and non-ccrrrtercial prograns. This copyright 
notice, however, nust be included in the final product. 

Disclaimer: 

This software is provided "as is", with no representation of 
fitness for any particular purpose. The user assumes all risks 
and responsibilities related to its use. 



♦ include <exec/types.h> 

♦ include <devices/ input event. h> 

♦ include <enec/r.e~cry.h> 

♦ include <oraphics/gfxbase.h> 
♦include <graphics/text.h> 

♦ .nclude <rntuiticn/intuit- :r. .:.> 
♦include <ctype.h> 

♦include <stdlo.h> 
♦include <functions.h> 



/■ 



Macro and constant definitions: 



♦define OCBECKIx) sw err( FILE 



♦define RON HEIGHT 
♦ define TCP~KASGIM 



LIRE 



*/ 
FOHC , ( (ULOKG) x|, hi) 



(TTJLO!lGTThi=5windS5->K'ort-5TKHeioht * 1|) 
I (ULOHS1 (hi->window->BorderTop ♦ \ 

hi->windcw->Pjo:t->Tx3aseline ♦ 1)1 
t (OLOHG) (hi->window->Height-hi->window->BorderBottom-l) ) 
I (ULOHG) lhi->window->Borderleft, t 5) I 
tlOLOMGI (hi->window->Width-hi->window->BorderRiqht - 5)) 
♦define 9ELP TDCMP ( (ULONG) icios-iiiirccH I gadgetup i gadgetdowh i keksize i \ 
RSFRSSBHIHDCtl I RMDB¥)I 



♦define 5GTTCK MARSH; 

♦ define LEFT CTRGIH 

♦ define SIGHT MARGIN 



♦define MAX LINES PER INDEX 

♦ define CHASE FEP.TjrTE?. 

♦define MAX CIUFSTER LINE 

♦define MAX"CHAES"i:i TITLE 

♦define HMCIOKES CltSRS 



♦define MAX ESCAPE SEC 



((UB7TEI 100) 

(lUETTEl 80) 

((UB1TEI 80) 

(tUBYIEl 80) 

ItlBYlEl 30) /* MOST s: less tha:: e-vtfe? aie 

1 Lire suss. 

■/ 

UU3TTEI 51 /• Kaxinua nunber of characters in 
escape sequences. 



♦define HELP SPACE FLAG 

♦define HEL?~HOLD SPACE FLAG 

♦define HELP EXTRA SPACE FLAG 

♦define HEIP'KOLD EXTRA. Trace fug 

♦ define HELP'LASTTOKEirFLAG " 



•/ 

((IUSHORTI 1] « 0) 

I (IUSHORTI 1] « 1) 

((IUSHORTI 1) « 21 

IHOSBORTI 1) « 3| 

(((USHORT) 1] « 41 



♦ifndef MAX 








♦ define MAX|x,y) ll(xl>ly)l ? Ix) : 


tyl l 






♦endif 








♦ itr.def MI!! 








♦define MI!Kx,y> (l<:-.l>(y)) ? tyl : 
♦endif 


(Mil 






♦define HELP COtll I1IUE ((SHORT) 01 








♦ define KELP-EOS 1 (short) 1) 


/' End or 


segment 


*/ 


(define help ecm ( (short) 2) 


/' End of 


Message 


'/ 


♦define BEL? EOF ((SHORT) 3) 


/* End Of 


File 


•1 


♦ define B2LF"EOL 1 (SHORT) 4) 


/• End Of 


Line 


■ 


♦define HELP EOT ((SHORT) 5) 


/■ End Of 


7 '.-.:. 


•1 


i:-!ir.e HELP FATAL 1 (SHORT) 6) 









♦define hsl?~last tcxe:: kshsp.t) '■ 



♦define IEO. LSHIFT 

♦ define lEOTtSETFT 
♦define IEQ SHIFT 
♦define IECTLALT 
♦define IEQ'RALT 
♦define ISO'ALT 
♦define HELP ESC 

♦ define BELETR 
♦define HELP DOWN 



:ec/jal:f:e?. lshift 
ieoualifier"p.sh;ft 
i ieq lshift"! ieq rsh1fti 

iequxlifiek lalt " 
ie0ualifier ralt 

IIEO LALT riEB SALT) 

Oy.45 /• Raw Seycode for HELP key. •/ 
0x4C /* Haw keycode for Cursor Up key. 
0x4D /■ Raw keycode for Cursor Down key. 



Function definitions for functions defined in this file: 



help (I; 

heiDAddToken II ; 
■heipAllocatelielpInstance (I ; 
helpAliocateLinelndexO ; 
•heinAIlccateSegment O ; 
helpBuildltneO; 
helpBuildSegr.ent () ; 
heipDisolay () ; 
heipDisbUyLinel); 
heipDisplayVisibleLinesO ; 
helpFreeAll (I ; 
heipGetToken!) ; 
helpHandleEscape ( ) ; 
helpHandlePreEscaped ; 
helpLocateXey ; 
helpSkipAliWhiteSpaceO; 
sw_err II ; 

/ .\ 

' External symbols needed (these nust be declared and initialized ' 

• elsewhere (i.e., in another file being linked with this one. ' 

\ - '/ 



BOOL 






static 


SHORT 




static 


struct 


Heiplnstance 


Bl ll LC 


void 




static 


struct 


Heip5egnentStruct 


static 


SHORT 




static 


SHORT 




static 


SHORT 




static 


void 




static 


v : 1 : 




static 


void 




static 


— -; 




static 


SHORT 




static 


void 




static 


EOOL 




static 


ECOL 




static 


void 





* The follewir.g libraries rveed to already be opened: 

extern struct Intuit iufiBase +lntuitionBase,* 
extern struct GfxSase *GfxBase; 



/ — *\ 

* Local static symbols. ■ 

\- */ 

static struct Image HelpPropIr.age; 
static struct Froplnfo HelpPrcpInfo; 
static struct Gadget HaiuPrcpGadaet - ( 

:r."L, 

-13, 12, 10, -24, 

:a::h::>3 I grelkigiti gpelbeight, 

GADGIMKEDIATE I FQLLOWKOUSE I RELVEP.IF?, 
PR0PGHX5EI, 

(APTR) SHelpPropImage, 
1IULL, NULL. 0, 

(APTR) iHelpPropInfo, 
0, 

HULL 
>." 

I , .\ 

' struct definitions. * 

\ •/ 

struct WindowVitalsStruct ( 

SHORT top, left, height, width; 

SHORT mih width, nin height; 

USHORT max width, nax~height; 

Char titlelKAX CHARS IK TITLE],- 
I; 

struct HelpSegraentStrucc ( 
ULOKG flags; 
ULCUS softsfyle; 
ULOCG softstyle_enable; 
ULCKG drawnode; 
LOHG frontpen, backpen; 
struct KelpSeorcentStruct *next; 
char bufferlCHARS^PER^BUTFER+l); 
UBYTE cursor; 

1; 

struct BelpLinelndeKStruct ( 

struct HeloLinelndexStruct *nezt; 

struct HelpSegmentStruct "IlinelMAX LUES PER I1IDEX1I; 



struct Relplnstance { 

FILE 'file; 

char *key; 

struct Reaember 'ReoerierKey; 

struct HelpLinelndexStruct *firstlnd' 

USHCST win top; 

USHGRT win left; 

USHORT win"height; 

DSflOM win*width; 

U3ITE 'win title; 

char token [MAX TOKEIt CHASStl]; 

char escape_burter[KKX_ESCA?E_SEQU] ; 

USHCRT pixper_line; 

USHTST pix_line_so far; 

U3ITE token_lengtfi"; 

USHORT total lines; 

USHORT tcp_llne; 

USHOST lines per page; 

USHORT flags! " 

ULONG current_drawrriode; 

LONG current_frontpen, current backpen; 

ULOKG current softstyle, current"_softstyle_enabIe; 

struct Screen T screen; 

struct Window 'window; 

struct Textr ont 'font ; 
I 



iastlndex, *currentlndex; 



BOOL help(FILE *file, struct Screen *screen, char 'key, 
struct TextFont *font) 

nescription: This is the entry point for the help utility. The 
application simply calls this function, when this 
function returns, the user is no longer requesting 
help. 

Inputs: file: A pointer to the opened (read access) help 

text file, 
screen: A pc-incer to the screen chat the help 

window is to be opened on. This can be 

NULL if the window is to be opened on the 

WorkBench screen, 
key: A pointer to the null terminated string the 

calling application wants to use as the 

help key. 
font: A pointer to the TextFont structure of the 

ALREADY OPENED font. This can be SOIL if 

help I) should use the default SastPort font 

Returns: TRUE if the hey was found in the help text file 
FALSE if the key was not in the help text file or 
if the file" passed in was NOLL. 



BOOL helplfile, screen, key, font) 

FILE •file; 

struct Screen *screen; 

char *key; 

struct TextFont *font; 

{ 



struct 
sscr: 

SRGRT 
LONG 



Helplnstance 
indexoffset; 
rc; 
filepos; 



hi; 
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static struct HewWindow NewWindsw; 

struct Window "window; 

struct KJLndOwVitalBStruct winvitals; 

if (!fiie) 

return FALSE; 



If ve were called with a file that didn't open 
we will return. This is in case the application 
(wrongly) didn't check the result of the focenO 
call. 



Here we establish some defaults for the help window. If the 
amplication passed a NULL screen pointer, we will open the window 
oh the KorkBench screen. Defaults are: 



21 pixels down. 

Flush with the left edae of the screen. 

Half the scresn height "for a custom screen, or half the 

height specified by GfxBase->BormalDisplayRaws. 

"he width □£ the custom screen or the width specified by 

?::.j .- ::. :r.aiDisplayColuflna. 

The hey string. It will be initialized by the 

helpLccateKey () function. 
nin height and width: Same as the height and width, 
max height and width: The size of the screen. 



tan: 
left: 
height : 

width: 

title: 



winvitals. top - 20; 
winvitals, left - 0; 
winvitals.height - (screen ? screen->Keight/2 : 

GfxBase->NarmalDispiayRows/2) ; 
winvitals. width - (screen ? screen->Width : 

GfxBase->NorMlDlspIayColumns} ; 
winvitals, min width - winvitals. width; 
winvitals. min^heiuht - winvitals. height; 
winvitals. max width ■ -G; 
winvitals. max~height - -0; 



/' 



Attempt to locate the helD key in the help text file. 
key is found, the winvitals structure will be updated to 



If the 
reflect 
key smecific values and the file will be positioned at the help 
text for the key read, if the key is not found, flash the screen 
and return. Note that we haven't allocated anything yet, so we 
don't have to free anything. 



if (heloLocateKey (fiie, >.ey, Swinvitalsl 
DisblayBeep(screen) ; 
return FALSE; 



FALSE) { 



filepos - ftellUile); 



Open the help window. 



Remember where the help text for this key 
started. 



*/ 

NewWindcw.LeftEdge 
HewWindow . TocEdge 
NewWindow. width" 
NewWindow. Height 
HewWindow . Detai Ipen 
NewWindow . Bl ockPen 
NewWindow. Flags 



HewWindow 
HewWindow 
HewWindow 
HewWindow 
HewWindow 
HewWindow 
HewWindow 
HewWindow 
HewWindow 
HewWindow 
HewWindow 

window 

/* 



IDCHrFiags 

EirstGadcet 

CheckMarfc 

Screen 

BitKap 

Type 

MinWidth 

MaxKidth 

Mir.Heiaht 

MaxHeight 

Title 



winvitals. left; 
winvitals. top; 
winvitals. width; 
winvitals- height; 
0; 
1; 

SIMPLE REFRESH I ACTIVATE I 
KIITOUWCLOSE ! WIHDOKDRAG I 

:::^:::-:3riT | sizeb3OTT0M t 

WIHTCWSIZIH5 i WHDOWDEFTH; 

I-iEL? I Z Zl\~ . ; 
HG1L7 

:;■:::: 

screen; 

HULL; 

(screen ? COSTCKSCREEH : WBEIOSCREEK) 

winvitals. min_width; 

winvitals. mas width; 

winvitals. adn~height; 

winvitals. max^heiaht: 

(UBY7E '(winvitals. title; 



OpenWindowjiNewWiridov) : 



If we couldn't open the window, return, 
anything. 



We still haven't allocated 



if (window 



BULL) return TRUE; 



How that the window is open, let's attach the prep gadget to the 
* eight window border. 



Heicrrcplnfo. Flags 
HelpPropInfo.VertPot 
He lp? ropln f o . VertBody 
HftlpPropfiadget.LeftEoge 

lielpFropGadget.TopEdge 
RelpPropGadget .Width 
HelpPrcpGadget, Height 



= :-;-: m KZz FrEE\-=:; 

- 0; 

- HAS30DY; 

■ -window->EorderRight + 2; 
* window->BorderTop + 1; 

- wLndow->BorderRighL - 4; 
■window-'>BorderBottcn - window->BorderTop -2; 



Addfeadget (wlndoWj iHslpPropGadget, -il); 

RefresnGList I&HelpPropGadget, window, HULL, 1L) ; 

/* 

• tfe T.iy. ill:.;;:.- the ;;elp:r.sti"e .".:■; ■:■;:■■.- , ?:.:: .. :--: '- : ;:.. 
■ for glcbal information needed throughout the help process. If 

* we can't allocate it, we will close the window and return. 

hi * TielcAllocateHelpInstanceffile, screen, window, key, (winvitals, 

font ) ; 
if (!hi) { 

ClcseWindow(window) ; 

return TRUE; 
) 



* How we start doing some interesting work. 

* loop until the user has had enough help. 
*/ 

for (;;) { 



We will stay in this 



1 Position the file to where the heln text for this key begins. 

* The first time we get here, this is redundant, However, we can 

* get here again if the user resizes the width of the help window. 

IvoidjfseelUfile, filepos, 0); 

ft 

* we don't knew how msny lines of text are in the helo message. 

* we allocate a line index capable of Xeepina track of 

* MAX LIKES PER INDEX lines. If the index gets full, we'll 

* allocate another one. 
•/ 

helpAllocateLrnelndex (hi) ; 

* At first it night appear that I haven't verified that I 

* actually allocated the index. But the for(| loop below will 

* terminate immediately if we couldn't since hi->currentlndex 

* will be NULL tsee helpAliocateLinelndexO ) . 
V 

for (indexOffset»Q; hi ->cur rent Index; jndexOffset++) ( 
if (indexOffset == MAX LINES PER INDEX) { 
/• - - 

* IE the index is full, allocate another one and restart 
1 the index count. All the indexes are linked together 

* so we won't lose any. 

indexOffset ■ -1; 

helpAllocateLinelnde^: (hi.} ; 
continue; 
J 

/■ 

* Here we will build a whole display line. This line will 

* contain one or more "segments". The line length and the 
■ number of segments needed are dependent on the fent used, 

* the size of the window and the number of text style changes. 

re * helpBuiidLinelhi, indexOffset); 

switch (re) { 

case HELP CONTINUE: 
case HELPTJOL: 

/• There are more lines to create. */ 

continue; 

case HELP EGH: 
case HELP^EOF: 

/■ There are no more lines to create. ■/ 
break; 

case HEL?_FATAL: 

/•He ran out of resources somewhere along the line. */ 
break; 

default; 

/* There is a bug in the software! '/ 

UCHECKI(ULONG)ECf; 

break; 

break ; 



* At this point, we have read in the help message and created 

* a complex set of linked data structures. We now are ready to 

* display the help message. Since we built our data structures 

* based on the window size, if we allow the user to change the 

* window size while we are rendering the text we might trash the 

* window borders. Therefore, I use the SIZEVERIFY flag as a 

* semaphore - until I clear the flag, I own the window. When 

* I clear the flag, the user can resize the window. Note that 

* I couldn't set the 5I2EVERIFY flag earlier since one must not 

* use any of the verify flags while accessing DOS. (Read the REX) . 
*/ 

ModifyIDCM?(hi->window, HELP^IDCMP | SIZEVERIFY]; 

re ■ helpDisplay (hi) : 
HodifyIDCM?<hi->window, HEL?_IDCMF); 

/* 

* If helpDisoiav II returns anything cut BEtP COHfflBOE, the user 

* is done. If HELP COKTIKUE is returned, the user resized the 

* window and we have to re-calculate the data structure. 
V 

if (re !■ KEL?_CONTINUE) break; 

/* 

* first off, return all tracked resources to the system. The 

* only memory we allocated that won't be returned here is the 

* memory we allocated for the Helplnstance structure [of course, 

* the Window structure is excluded from this, too) . Also, 
1 reset all Helplnstance values. 

FreeReaember Uhi-^r.errisr:;^., c;:::-) TF.UE) ; 

hi->RememherKey - HULL; 

hi->firstindex - NOLL; 

hi->iastlndex ■ NULL; 

hi->currentlndex - NULL; 

hl->t3keni0] - l \0'; 

hi->escape_buffer[0] » % W ; 

hi->piv_line_so far ■ 0; 

hi->token length" » 0; 

hi->flags - 0; 

hi->total lines - 0; 

hi->tcp_lTne - 0; 
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AG's TECH 



/* Clear the window, */ 
SetrtFen{hi->window->EPort, OL) ; 
SetDrHdthi->windaw->RPorc I JAK1|; 

RectFill (hi->window->R?ort ( (LONG)hl->win,dow->BorderLe£t ( 
(LONG) hi->wind3w->BorderIop, 

(LONG) (hi->window->Width - hi->window->BorderRight - 1}, 
(LONG) (hi->window->Height - hi->*undow->BoideiBottoni - 1)1; 

/* Da it all over again. */ 



' We ate all done. Free all resources, 
• structure and class the Window. 
*/ 

helpFreeAll (hi) ; 

return TRUE; 



including the Helplnstance 



static struct Belplnstance •helpAllocateilelpInstaHncelFILE 'file, • 
struct* Screen * screen, 
struct Window "window, char *key, 
struct WindowVitalsStruct »wv, 

struct Text Font 'font) * 

* 

Description: This function is used once per help!) session. It * 

allocates and initializes the Helplnstance data * 

structure, a pointer to which MUST be passed to all * 

helpO related functions. * 

Inputs; file: A pointer to the opened (read access! help ' 

text file, * 

screen; A pointer to the screen that the helo * 

window has been cpened on. This can be * 

NULL if the window has been opened on the * 
WorfcBench screen. 

window: A pointer to the opened help window, * 

key: A pointer to the null terminated string the * 

calling application wants to use as the * 

help fcey. * 

wvt A pointer to the initialized * 

WindowVitalsStruct data structure. * 

font: A pointer to the Te.xtfont structure of the * 

ALR1ADY OFI1JID font. This can be NULL if * 
help (J should use the default RastPort font.* 

Returns: A pointer to the allocated and initialized Helplnstance * 

data structure, or NULL if the data stricture could not * 

ba allocated. This is the ONLY data structure that is * 

allocated using AllocMesil) instead of AilocHerae-TiaerO . * 
As such, this must be explicitly FreeMeal) 'ed. 



V 



static strict Helclnstance *helc.-.llocateHelp:nstance(file, screen, 

key, wv, font) 
FILE 'file; 

struct Screen 'screen; 
struct Window + win daw; 
char *key; 

struct WindowVitalsStruct *wv; 
struct Text Font 'font; 

struct Helplnstance *hi; 



hi 



[struct Helplnstance *)AllocKen((LCJJG)siseof {struct Helnlnstancel , 
MEMF CLEAR) ; 



if (hi) ( 

hi->file ■ file; 

hi->screen - screen; 

hi->windoH - window; 

hl->key ■ Xey; 

hl->win too - wv->top; 

hi->win_left « wv->left; 

hi->win width - wv->width; 

hi->win~height - wv->heiaht,' 

hi->win~title - (UBrlE *)wv->title; 

hi->Re. i semrjerKey = NULL,' 

hi->current_draw.ode - JAM1; 

hi->current frontpen ■ 1; 

hi->current^backpen - 0; 

hi->current softstyle - hi->current softstyle enable - 0; 

hi->pix_per^line - RIGHT_HARGli; - LTFT_KAF.Giir+ 1; 

If (font !■ NULL) ( 
hi->font - font; 

(void)SetFont (hi->window">RPort, font! ; 
) else [ 

hi->font ■ hi->window->RFort->Font; 
I 
} 

return (hi) ; 



static void helpAllocateLineIndex<struct Helplnstance «hi) 

Description; This function is used to allocate ar. index for a 
set of lines. Each line contains one or more 
segments, which are linked together. An index can 
keep track of HAX_LIN5S_PER INDEX lines. If the 
help message contains rare Tines, another line 
index needs to be allocated. This function 
automatically links all allocated line indexes into 
the Helplnstance data structure. 

Inputs: hi; a pointer to the Belplnstance data structure. 

Returns: Kathing. hi->currentlndex will always point to the 
allocated index. If hi->currentlndex is NULL, the 
allocation failed. The data structure 
is allocated using nllccRemenher{) , so that it will 
be freed when AliocFreeO is called. 
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static void he.pAllocateLinelndexOli) 
struct Helplnstance *hi; 

struct NelptlnelndexStruct "hll; 

hli - (struct HelDLineTndexStruct *) 

AllccRenerr.berl4hl->?:e:7.e:=l)erSey, 

I LOHG) sireo f (st ruct HelpLinelndexSt ruct) , 

KEHF_CI£AR) [ 

II Itlli) I 

if <hi->firstlndex == HULL) { 

hi->firstlndex = hli; 

hi->last Index ■= hilt 
I else I 

hi->lastlndex->next - hli; 

hl->iastlndex - hli; 
1 
) 



hi->currentlndex = hli; 



* static struct HelpSegmentStruct *helpAliocateSegn:ent ( 

* struct Helplnstance *hi) 

* Description: This function allocates a segment that is to be 

* linked into the current line. 



Inputs: hi 
Returns : 



a pointer to the ftelplnstance data structure. 



A pointer to the allocated KeltSsgrr.vr'.'-Struct or 
BULL if the allocation fails. The data structure * 

* is allocated using AllocRejiember ( I , so that it will * 

* be freed when Allocfreet) is called. * 

\. -_./ 

static struct HelpSegnentStruct »helpAllocateSegriant (hi> 

struct Helplnstance "hi; 

struct HeipSegcentStruct 'hs; 

hs =■ (struct HelpSegmentStruct *) 

AllocReEember lsU->ReaemberKey, 

(LONG} slreof {struct ilelpSeonentStruct) , 
MEKF CLEARI ; 
return hs; 



static BOOL helpLc-cateKey(FILE "file, char "Key, 

struct WindowVitalsStruct *wv) 

Description: This function searches a file for the specified 
help key. If the key is found, the 
WindowVitalsStruct is modified to reflect any key 
specific values. 

Incuts: file: A pointer to the opened (read access) help 

text file, 
key: A pointer to the null terminated strinc the 

calling application wants to use as the 

help key. 
wv: A pointer tD the default initialized 

WindowVitalsStruct data structure. 

Returns: FALSE if the key was not found in the help text 
file. 
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* TRUE otherwise. In this case, *wv is nodified to 

* reflect any key specific values. Also, 

* the entire key string Us specified by the 

* help text file) is copied into wv->title|]. 
\* ____ _______________ ____ 

static BOOL helpLocateKeylfile, key, wv) 

FILE «file; 

char *key; 

struct wmdowVitalsStruct *wr; 

char buffer[B2]; /* 80 chars man,, plus \n and \0 »/ 
char *bufptr; 
U3"TE keyiength; 
SHORT temp; 

U5H0RT left - -0, top - -0, width - '0, height 
min_vidth « -0, min_height - -Q; 



-0i 



/* Rewind the file. 
fseek(file, Wi 0)r 



f* 



7 



Notice that if the key is "abc" and the file contains 
■ an entry keyed by "abcdef, we declare a catch. This 

* is done an:icipatinn applications that wish to allow the user 

* to enter only enough" characters to make a unique match. I 

* don't look for a unique match per se, but I do key to the user's 

* input. 
V 

keyiength - sirlen (key) ; 

while Ugets (buffer, 82, file)) I 
if l*bu£fer !- *%'} continue; 
if (strncmp{4buffer[l], key, keyiength)} continue; 

/* 

* The key was found. He will now determine the window values 
» and title. 

*/ 

bufferjstrlenfbufferl-l] ** '\C; f* Change the \n to a % \0' . */ 

/* 

* Keep scanning the buffer until we reach the key string delimiter 

* (*_') or the end of the buffer ,'\0'}. 
'/ 

forlbufptr - fcbuffertkeylength+ll; 

(*bufptr !- *\0'| -S {"bufptr !- *8'); 
bufptr++, keylength++) ; 

/* 

' Me nov copy the key string into the wv->title(] buffer. The 
' above loop cade keyiength equal to the length of the key string. 



itle [keyiength] - '\0*; 



we scan the buffer 



strncpy(wv->title, _buffer[ll, keyiength) ; 
wv->t_f ■' 

/* 

* If we found the key string delimiter {' 

* for the window values . 
*/ 

if Cbufptr — '_*] { 
bufptr+t; 

sscanf (bufptr, "id/id/id/id/td/WW/td", 
-left, stoo, _width r sheioht, 
train width', ■.-::. height, 
£wv-?raajs width, £wy->in_x height! ; 
} 

/* 

* If any of the local variable are no longer -0 (-1), we want to 

* override the default values, 
*/ 



if (top 
" left 



!■ -0) wv->top - top; 
if (left !- -0} wv->left - left; 
if (width !- -0) wvowidth - width; 
if (height !- -0) wv->height - height; 
if (minjwidth t* -0) wv->nin_wi_tn = min width; 

else wv->min_width = wv->width; 
if (min_beight != -0) wv~>nin height = min_height; 

else wv">min_height ■ wv-£height; 

if ( (wv->max_width !- "0) -- (wv->Mn_width > wv->max_widthl ) ( 

temp - wv"->mln_width; 

wv->nin_width M wv->nax_width; 

wv->max width « temp; 
} 

if ( (wv->max_h eight !« -0) &. [wv->min_height > wv->max_height|) ( 
temp • wv->nun height; 
wv->rain height =■ wv->max_height; 
wv-:>nax"height - terns; 

} 

return TRUE; 



key i 
i FALSi 



/* 



* static void helpFreeAll {struct Helplnstance *hi) 

Description: This function returns all system resources 
allocated by the help utility. 

Inputs: hi; a pointer to the Helplnstance data structure. 

Returns: Nothing. 



static void helpFreeAll (hi) 
struct Helplnstance 'hi; 

if < hi ) ! L , ■ , . 

if (hi->window| Close>:indow(hi->window) ; 

if (hi->ReitercberKey) PreeRemenb@r(4hi->RenemberKey, (LONG} TRUE) ; 
FreeHea( (char # }hi, (LONG) sizeof (struct Helplnstance)); 



static SHORT helpBulldLine (struct Helplnstance *hi, 
SHORT indexOffset) 

Description: This function creates one line of help text. The 
line isn't displayed yet, only read into memory and 
processed. 

Inputsr hi: a pointer to the Helplnstance data structure. 
indexOffset: the offset into the current line 

index that this line should be assigned to. 

Returns: HELP FATAL if we ran out of resources trying to 
- build this line. 
Whatever helpBuildSegmeht returns. 



static SHORT heloBuiidLinelhi, indexOffset) 
struct Helplnstance *hi; 
SSCRT indexOffset ; 
{ 

Struct HelpSegmentStruct 'segment; 

SHORT rc; 

/* Assume we aren't going to be able to do this. */ 
rc - HELP FATAL; 



' Increment the number of lines so far, The line width in pixels 

* is zero at this point |we haven't added any characters yetl , 

hi->total lines++; 
hi->pix_Hne_so_far ■■■ 0; 

f* 

* If there is a token left over from the previous line, we have to 

* check if one or two spaces are needed to follow the token. 

* HELP_5FACE_FLAG and HELP ExrRA_SPACE_FLAG each indicate we need 

* one space- If either of~these are set, we set the corresponding 

* "HOLD 6 flag: HELPJiOLDJPACE FLAGS and HELPJ0LO EXTRA Jf ACE FLAG, 

* Then we clear the current flags. 

if ((hi->token length > 0) ii <hi->flags. & HELP SPACE FLAG)} { 

hi->flags T-. HEL? HOLD SPACE FLAG; 
} else ( ~ 

hi->flags £- -HELP HOLD SPACE FLAG; 
I - - " 

if ((hl->token lentith > C) _£ <hi->£laqs - HELP EXTRA SPACE FLAG)) 1 

hi->flags T- HELP_HOLD_EXTRA_SPACE_FLAG; - - - 

) else i 

hi->flags _» -HELF_HO___EXTRA_5PACE_/LAG; 

hi->flags 4= - (HELP_SFACE_?_AG I HE_P_EXTRA_SPACE_FLAG) ,* 
ft 

* Lines are made up of one or more segments. The for{) loop will 

* automatically terminate if a segment couldn't be allocated. For 

* each segment we allocate, we link it into the line and build the 

* segmentl As long as helpBuildSegaent 1) returns h*ELF_C0NTItfUE, 

* another segment is needed for the current line. ~ 

for ({segment. - (hl->currentIndex->iine[lndexOffset] - 
helpAllocateSegment (hi) ) ) ; 

{segment && (rc-helpBuildSeoment (hi, segment)) — EELP_COSTINUE) ; 
segment = (segment ->next = SelpAllocateSegment (hi) ) | ; 

I* 

* If we exited the for O loop because we couldn't allocate a segment, 

* return IiSLP_FATAL, otherwise, return the result code returned by 

* helpBuildSegment () . 

if (Isegment) return HELP FATAL; 
return rc; 



static SHORT helpBuildSegment (struct Helplnstance *hi, 

struct HelpSegmentStruct «segment) 

Description; This function builds a single segment. It will 

return if there is no room left for more characters 
in the segment, if the help text file indicates 
that a change of text style is needed or if we 
reached the end of the help text message. 

Inputs: hi: a pointer to the Helplnstance data structure, 
segment: a pointer to the current segment. 

Returns: HELE_CONIINUE if this segment was built and another 
segment Is needed for this same line. 

HELP EOF if the end of file has been reached in the 
Help text file. 

KELP_EOH if the end of the help message has been 
reached. 

HELP EoL If this line is to be terminated. 



static SHORT helpBuildSegment <hi, segment) 

struct Helplnstance *hi; 

struct HelpSegmentStruct 'segment; 



* Each segment has its own text style. By this I mean: front pen, 

' back pen, draw mode and soft3tyle (italics, bold, underlined, plain}. 

* The Helplnstance keeps track of the current set of values so that 

* each segment can determine its set. 

segment->frontpen ■ hi->current frontpen; 

segment ->backpen = hi'>currentn3ackpen; 

seguent->drawmode - hi->current drawmode; 

segment->softstyle - hi->current7_softstyie; 

segment ->softstyle_enable - hi->current_softstyle_enable; 
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' If there is no token left over from the previous segment, we look 

■ to see if there are any text style changes being requested in the 
* help text file. Since we haven't put any text into this segment 

1 yet ve can change cur text style values from ones we just set up 

■ without violating the rule that each segment is cade up of 

■ text that has all the sane text style. 

if (hi->token_length » 0) helpHandlePreEscape (hi, hi->file, segment); 

/• 

" Itow we keep adding tokens to the segment until helpAddloken ( ) 

■ returns anything but HELP_CONTINUE , 

whileKrc « helpAddTokenlhi, segment) ) -- HEi=_CC:rri!i-E| ; 

switch (re) ( 

case KELF EOS; 
/» " 

* This means that a new text style is needed or that there 

* is no room left in this segment for a new token. Ke return 
' HILT_C0!IT11IUE so that helpBulldLine II will allocate a new 

1 segment for the current line and call this function again. 

return HELP CcOTIRUE; 
case HELP EOF: _ 
case iliunoK: 
case HELPICL: 

/• " 
' Me reached the end of the file, end of the message or 

* we know we reached the end of the line. The calling functions 
' will know what to do with these results. 

•/ 
return re; 

default: 

/■ Software bug! •/ 
DCBBOetlBMHGIrei, - 

■ 

/•KCTREACHEO*/ 



static SHORT helpAddloken (struct Helplnstance *hi, 

struct HelpSegxentstruct "segment) 

Description: This function adds a single token to the current 
segment. 

Inputs: hi: a pointer to the Helplnstance data structure, 
segment: a pointer to the current segment. 

Returns: HELPjroirriNtn: if a token was successfully added 

and another token might be able to be put 

in this segnent/line. 
HELP_EOL if the token just added is to be the last 

for the current line, 
jirrc jos if next token couldn't fit in the current 

segment . 
Anything else helpGetTcken I) nay return. 



static SHORT helpAddTokenlhi, segment! 

struct Helplnstance "hi; 

struct HelpSegmentStruct "segment; 

SHORT re; 

DBYTE space^adjust; 

UBrTE 'cursor;' 

U5HOR7 char count, pix_count; 

char "buffer; 

USHORT flags; 

/• 

* Assume that we will be able to add the next token to the 

* current segment. 

re - HELP_COHTI!JUE; 

buffer - segrcert->buffer; 
cursor = isegment->cursor; 
flags ■ hi->flags; 

/• 
" space_adjust will be set to the number of spaces we need to 
' add to the next token. 



space adjust ■ ((flags I HEIR SPACE FLAG) ? 1 i 01 t 
((flags 5 HELP" EXTRA" SPACE ELAGI ? 1 
((flags S HEL=-]IDLD 5RACE FLAG) J 1 : 
((flags S HELnc.LO-"ExTRA"SPACE FLAG! 



0) * 



If there is no token outstanding (a token that was previously 
read but couldn't be fit into a previous segment), we will read 
the next token from the help text file. 
/ 
l"hi->token »■ '\0') ( 
re - helpGetTokenlhi, segnent I; 

switch (re) ( 

case HEIR LAST TOKEN: 

< The token we have just read is to be the last token 

* in the current line. This happens when a help text 

* line is terminated with "Xn". 
V 

hi->flags I- HELP LAST TOKEN FLAG; 

re - HELP EOL; " 

/* fall tlirough "1 
case HELP COIITINUE: 
case HELFTIOS: 

creak; 

default: 

return (re) ; 
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..329 


SUPRA5O0XP/4OH/512K 
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Circle 183 on Reader Service card. 



" char_count is the number of characters that the token contains 

* plus the number of spaces that must be added to it. 

* pix_count is the number of pixels wide the token is (including 

* the spaces I . 

char_count - space_adjust * hi->token length; 
p!x_count *» sbace_adjust*hi->font->tr XSize -F 

TextLength(hi->window-5SEort, hi->token, 

(LONG]hi->token__length) ,- 

/• 

* If the pixel size of this one token is larger than the number 

* of pixels we can fit in a whole line, we will prematurely terminate 
1 the help message. It is up to the author of the help text file 

* to make sure that the user cannot size the help window too small. 
•/ 



if (pix count > hi->pix tier line) I 

return HELP ECX; 
I 



1 If the pixel size of this one token won't fit on the current 
• line (we know It'll at least fit on its own line from the above 
" conditional), we'll terminate the current line. This token 
' will then become the first one used on the next line. 
'/ 

if ((pix count t hi->pix line so far] > hi->pix per line) ( 
return HELP EOL; - - - 

} 



.11 go . 

itself cannot hold this token, we'll terminate the current segment. 
This token will become the first token of the next segment, which 
will be the next segnent for the current line. 



if ([char count t "cursor) > CHARS PER BQFFEF.I 

return HELP EOS; 
1 



' U either HEL?_SPACF. FLAG or KELP EXTRA SPACE FLAG are set, the 

' previous token (on tRis linel needed to"be followed by space(a) before 

" this token is inserted into the line. 

■/ 

if (flags i HELP_SPACE FLAG) I 

buffer! |"cursor)*+T " ' '; 



if (flags i BILE HUM SPACE FLAG) ( 

buffer! ("cursor)**T - > T ; 
) 



* Add the token to the current segment. 
'/ 

strcat (buffer, hi->token); 
■cursor 4- hi->token_length; 

/* 

• If either HELP BOLD_SPACE_FLAG or HELR_HOI£) EXTRA SPACE FLAG are set, 
' the current tok"en must be followed by spaceTs) on the current line. 

if (flags 4 BEL? HOLD SPACE FLAG) | 
buffer! fcursorl+T] = '-'; 
hi->flags i° -helphold space flag; 
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if If lags S HELFJiOLD EXTRA_S?ACE_FLAG> ( 
buffer! ('cursor! +TJ = * l ; 
hi->£laas S- -HELP HOLD EXTRA SPACE FLAG; 



Adjust the pixel count for the line. 



hi->pix_line_so_far +» plx_count; 

!• 
" Since we u«ed the token, clear out the holding buffer for it. 

(void)setmemlhi->token, HAX_70XEN_CHARSU, 0) ; 
hi->token_lencth - 0: 

/' 
* If this token had to be the last one for this line, return HELP EOL, 
*/ 

if (hi->£lags S BEL? LAST TOKEN FLAG) ( 
hi->flags 1- -HEO LAST TOiEl FLAG: 

return HELP EOL; - - - 



return re; 



static SHORT helpGetToken (struct Helplnstance 'hi, 

struct HelpSegment struct * segment) 

Description: This function reads a single token from the help 
text. 

Inputs: hi: a pointer to the Helplnstance data structure, 
segment: a pointer tc the current segment. 

Returns: HELP CONTINUE if a token was successfully read. 

HELPT:of if the end of file was reached before any 

characters were read, 
HELP_E05 if next token couldn't fit in the current 

segment . 
HELP EO.M if the end of the help text nessage was 

reached. 



static SHORT helpGetToken(hi, segment) 

struct Eelplnstahce *hi; 

struct HelpSegrcsntStruct 'segment: 

FILE 'file = hi->file; 

lnt c, cZ; 

USHOST 1-0; 

SHORT re; 

BOOL done, lastKasADOl-FALSE; 

hi->token length - 0; 

hi->fiags~E= - (H£LP_SPACE_FIAG I H£LF_EXTRA_S?ACE_FLAG) ; 

f or (dor.e'FAISE; ! dene; ) ( 



■ 



Read the next character from the file. 
•/ 
c - getclfile) ; 

switch (c) ( 
case EOF: 
/' 

* If we have reached the end of the file, then 

* we have to see if we have read any characters for 

* this token. 
•/ 

if U > 0| I 
/* 

* This token is not empty. We will return 

* HELP CONTINUE. The next tine helpGetlokenl) is 

* called, we will return HELP EOF. 
*/ 

re - HELPCOHTIWUE; 
} else { 
/> 

* This token is empty. Just return HELP EOF. 
V 

re - HELP EOF; 

I 

' In either case, we are done with the processing for 

" this token. 

•I 
done - TRUE; 
break; 

case 'W: 

■ If the character just read is the special "escape" 

* character (not the ASCII ESC eharacterl , we have some 

* special work to do. First, we will put the character 

* back into the file. Then we will process the escape 

* sequence. There are some sequences that don't cause 
1 us to terminate the current segment. 

•/ 

(void)unqetc(c, file); 

if Krc^nelcHandieEscaeelhi, segment, file, si)) 
— H£LS_COSTISIUEI 
continue; 

/• 

* We have reached one of the following conditions: 

* 1) end of segment 
' 2) end of nessage 

* 3) end of token (no more room in current token buffer!. 
'/ 

dene = TRUE; 

if (re — HELP_E0S) i 

* If there is any white space following this token, 

■ move the file pointer past it and remember that we 



* need a space. 
V 

if (helpSkioAlliihite5pace<hi, file) I 
hi->flags I- EELP_5PACE_FIAG; 

) else if (re — HELP EOT! ( 
/* 

* If helpHandleEscapeO returned HEL?_EOT it determined 

* that there was no more room in the current token, **e 

* are done getting this token. 



I 



re ' HELP COHTTMffi; 



break; /* EOS, EOM, EOI •/ 
default : 

/* 

* We've already handled most of the special cases. We 

* still have to handle whitespace, periods (two spaces 

* follow periods under most circumstances) and, of course, 
■ "normal characters. 

'/ 
if lisspace(c)) ( 

if ((c — '\n') K lastWasADotl ( 

(void) helpSkipAllWhiteSpace (hi, file) ; 
hi->flags I- 

(HELP SPACE FUG I HELP EXTRA SPACE FLAG); 
re = HEL?~COIiTimiE; 
done - TRUE; 
break; 
1 

if tie — ' ') u lastWasADotl I 
c2 - getclfile); 
(voidfungetc(c2, file); 
if <c2 — ' ■) I 

(void)helpSkipAHKhiteSpace(hi, file) ; 
hi-> flags [■ 

IHELP SPACE FLAG I HELP EXTRA SPACE FLAG]; 
re - HELP'CONTITTOE; 
done - TRUE; 
break; 
) 
) 

(voidlheipSkipAllWhiteSpacelhi, file] ; 
hi->flags I- HELP SPACE FLAG; 
re - HELP COKTIKUF; 
done = IP.UE; 
break ; 



(<c 



'.') ? TRUE : FALSE); 



■ Store the character in the token buffer, 
•/ 
hi->tokenU++] ■ c; 

it U =■= MAX TCKFJI CHARS) I 
ft - - 

* If there is no more room in this token for more 

* characters, we'll return and let the calling routine 

* call us again. 
'/ 

re » HELP CCHTMOE; 
done - TRUE; 
hreak; 



hi->token_length - i; 
return (rcl ; 



static BOOL helpSkipAllWhiteSpace (struct Helplnstance 'hi, 

FILE 'file! 

Description: This function adjusts the file so that when this 
function returns the next character read from the 
file will not be a white space character (the file 
may be positioned at the end-of-file) . 

Inputs: hi: a pointer to the Helplnstance data structure, 
file: a pointer to the FILE used for help text. 

Returns: TRUE if any white space was skipped. 

FALSE if no white space was skipped or if the 

file was at the End-Of-File when this function was 
called. 



static BOOL helpSkipAllWhiteSpace (hi, file) 
struct Helplnstance 'hi; 
FILE 'file; 
I 

int c; 

BOOL re ■ FALSE; 

while He - getc(filel) !- EOF) ( 
if ('isspace(c)) { 

(void)ungetclc, file); 
break; 
( else re • TRUE; 
} 
return re; 



* static void heioHandlePreEscape (struct Helplnstance 'hi, 

* FILE 'file, 

* struct HelpSegment Struct 'segment) 

* Description: This function processes help text escape sequences 
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that exist before any characters have been put into 
the current segment. The segment text style will 
be modified as'recuested by the help te:-:t. Any 
unknown escape sequences will be discarded. 

hi: a pointer to the Helplnstance data structure, 
file: a pointer to the FILE used for help text, 
segment: a pointer to the current segment. 

Nothing. However, the segment tvpe style fields 
(softstyle, drawmode, frontpen, bachpen) will be 
updated and the file sill be positioned past the 
processed escape sequences. 



static void helcHar.dlePreEscacelhi, file, segment) 

struct Kelplnstance 'hi; 

FILE "file; 

struct HelpSegmentSLruct 'segment; 

BOOL done; 
int c 

fer(done-FALSE;!done; I ( 

c - getc(file) ; 

/* 
* If the character read is not the "\" (the first character 
of escape sequences), put the character back and ieave the loop. 



if [c !- '\\'| [ 

(void)ungetc(c, file) ; 

done - TRUE; 

break; 

1 

/* 

* We now read the next character and process the escape sequence. 

c - getc(flle); 
switch Ic) { 

■ SoftStyle requests: 

case *B' : /* Bold On */ 

segment ->soft style ;= F5F_HCLD; 

breafc; 
case l U* : /* Underline On */ 

seg*ent->softstyle !« F5F UNDERLINED; 

break; 
case *I* : /■ Italics On */ 

segment->softstyle 1= FSF_ITALIC; 

break; 
case V: /• Bold Off */ 

segxent->so£tstyle S-= -FSF SOLD; 

break; 
case 'u' : /• Underline Off */ 

segment->soft style 5- -FSFJH.'DERLIIJEO; 

break; 
case 'L't /* Italics Off •/ 

seqicent->softstyle s- -FSF ITALIC; 

:.:> ; :-:; 
case 'I!': /* Bold Off, Underline Off, Italics Off '/ 

seament->softstyle » 0; 

break; 

/' 
' Drawmode requests: 

case *J f : /' JAM1 or JAM2 »/ 
c - getc(file), 1 
switch ic) { 
case 4' : 

segment->drawmode » hi->current_drawjnode - JAM1; 
break; 
case *2' : 

default:/* Use JAM2 if woe unknown type is specified. */ 
se3ment->dravmsde - hi->current dravmode = JAK2; 
breai; 
} 

br^ij;; 
case 'X' : /' XOR (COMPLEMENT) ■/ 

seaicent->drawm;de - hi->current_drawxcde « COMPLEMENT; 
break; 



* Pen color requests: 
V 
case X' \ /* Front Pen */ 

(void) fscanf (file, "\l&", &segEient->frontpen) ; 

hi->current_frontpen n segmer,t->frontpen; 
break ; 

case *R' : /' Back (Rear) Pen. Couldn't use *B r . 
(void) fscanE (file, "Ud", tsegment->backpen) ; 
hi->current_backpen ■* segroent-J-backpen; 
break; 



■ * Anything else. Valid non-text style escape sequences need 

* to be put back. Ail others will be skipped. In any case, 

• we leave the loop. 



'U'l II <e « V) II (c — 



default: 

if ({c — v s') II |c — 
fseek(file, -2L, 1}; 
done - TRUE; 
) 



segment ->soft5tyle_enable - FSF_B01D | FSF_IIAL1C I FSFJIHDERLINED; 
hi->eurrent_softstyle = segiEent->softstyle; 
hi->current_softstyle_enable - segment->softstyle_enabie; 



')} [ 



static SHORT helc-iar.dieSscape (struct Heioltistance "hi, 

struct HelpSeg:aentSUuct *segment, 
FILE *file, USilORT *cursor_ptr) 

Description: Ihis function processes escape sequences in the 
help text when the current segment already has 
characters in it. Host escape sequences cause the 
current segment to be terminated . However, there 
are a few thai: are used to modify the current 
segment. 

Inputs: hi: a pointer to the Helplnstance data structure. 
segment: a pointer to the current secme.it . 
fiie: a pointer to the FILE used for help text. 
cursor_ptr: a Dointer to the counter used to keep 

track of the number cf characters in 

the current token, 

Returns: HELP EOF if End-Of-File reached. 

H2L?~ECH if End-Of-Message reached, 

HEL?~EC5 if current segr.ent is completed, 

KEL?_=.QI if we can't fit any more characters in the 

current token. 
HEL?_CQN7INUE if more characters can be placed in 

current token and we have processed all 

escape sequences we could. 
Note also that *cursor ptr is modified to reflect 
any characters that this function inserts into the 
current token, and that the file is positioned to 
the first character not processed by this function. 



static SHORT helpHandl&Escaoe (hi, segment, file, cursor otr) 

struct Helplnstance *hi; 

struct He lpSegment Struct *segsent; 

file 'file; 

U3HQRI 'cursor ptr; 

int c; 

fori;;) < 

C - getc(file) ; 

/* 

* If the character read is not the w \" |thfe first character 

* of escace secuencesl, put the character back and return. 

if Ic l» '\\'l t 

(voidlungetclc, file); 
return HELP CONTINUE; 

) 

t* 
■ We now read the next character and process the escape sequence. 

c - getc{file); 

switch Ic) { 
case EOF: 

return HELP eof; 



case 'g' 

retu 

case 'B' 

case *b' 

case l I* 

case '1' 

case 'U' 

case V 

case 'N' 

case 'X' 

case 'J' 

case "C 

case '&* 



n HELP EOM; 



All of these require a new segment. 



f seek (file, -2L, 1) ; 

return £ELP_EOS; 

default: 

switch (c) ( 

case *£' : /* Force a sinale space. */ 
c * * *i 

/* fall through V 
case *\\* : /• Force a "\ r character. */ 
if (*cursorj)tr < MAXroKEH CHARS) { 

hi->cokeni {'cursor ptr)T+j = c; 

return HELP_CO!4TIMUE; 
) else ( 

tseeklfile, -11, i|; 

return HELP EOT; 
} 

case *n* : /' Force a new line. */ 

IvoidlhelpSkipAllWhiteSpaceihi, file); 
if |-cursor_ptr > 0) { 

' If there any characters in the current 

* token, we need to return HELP LAS" TOKEN 

* so that those characters will~be "Hushed", 
'/ 

return HELP LAST TOKEN; 
} " " 

return HELP_EOL; 

default: /• A sequence we don't understand. "/ 
(void)ungetc (c, file) ; 
return HELP CQKTIHDE; 



I 



J 



/* KOT_REACHED V 
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static SHORT helpDisplay (struct Helplnstance 

Description 



•hi) 



Ihis function is sailed to actually display the 
help test message Icr the help key. The message 
has already been read and processed into the 

* necessary data structures." If the width of the * 

* help window changes, the nessage will have to be 

' reprocessed before this function is called again. ■ 

* However, while in this function, the user will be ■ 

* able to scroll the help message (via keyboard or 

* a proportional gadget) . 

* Inputs: hi: a pointer to the Beiplnstance data structure. 

* Returns; EiEL?_ECH if the user wants to quit the help 

* message. 

* EEL? CffiiTIXuE if the user changed the width of the ' 
1 helD window. • 

\ - / 

static SHORT helpDisplay (hi) 
struct EelDlnstance 'hi; 
' 
struct IntuiHessane 'irnsc; 
ULGIJS class: 
USHORI cede, qualifier; 
EOGL redisplay, quit: 
HOBD vertFct, vertBody, 
hidden. 
Overlap ■ 0, 

totaiLines - hi->total_lines, 
visibleLines, 
tcpLine • 0; 

hi->lines cer page - visibleLines - 

(30ITOk_K/£Gn! - TCPHSEGIU + IROW_HEIGHT/2) ) / ROWJ-EIGHI; 

/* The following code seoment coir.es from RKJ1 Intuition: gadgets page B5 »/ 
I* Find the number of hidden lines, those that don't fit in the 

* visibleLines portion. It turns out to be useful in further 

* calculations. 
*/ 

hidden - MHUtotalLlnes - visibleLines, 01; 

/* If topLine is so areat that the remainder of the lines won't even 

* fill the displavarjle area, reduce tonline: 
*/ " ' 

if (topLine > hidden] 
topLine - hidden; 

/* Body is the relative size of the proportional gadget's body. It's 

* sire in the container reoresents the fraction of the total that is 
1 in view. If there are no lines hidden, then Body should be 

* full-sire IMAXBODY) , Otherwise, Body should be the fraction of 

* (the number of disolayed lines - Overlap] over 

* (the number of total lines - Overlap) . 
•/ 

if (hidden > 01 1 

vertBody - (DWORD) 

{ (ULOKS) [visibleLines-Overlaol 'MAX30DY/ ItotalLlnes-Overlap) I ; 

vertBody = t&XBODY; 

/• Pot ;e the ccsitior. of the crcccrtional gadget body, with lero 

■ mear.ir.s that the scroll gadget is all the way up lor leftl, 

* and full (KAXPOII meaning that the scroll gadget is all the way 

* down (or riaht] . If we can see all the lines, Pot should be zero. 

■ Otherwise, Pot is the tcp displayed line divided by the number of 
unseen lines. 



V 

f (hidden > 0] { 

vertPot - (UW3RD) l((OLO!J3) tcpLine 
else ( 

vertPot ■ v; 



MAXfOT) / hidden]; 



End of excerpt from RKM •/ 



HelpPropInfc. Flags - ACTCRfOB I FREEVERT; 
Help? roplnfe. VertPot = vertPot; 
HelpProplnfo. VertBody = vertBody; 

KewModifyPrcplsHeicPropGadget, hi->window, ITJLL, 
[ULOK3|i!elp?roDlnfe. Flags, 
-1L, (LOIIG) vertPot, -It, (LONG) vertBody, 1L) : 

/■ 

* The proportional gadget has been calculated. How display all the 

* lines that will fit in the window. 

'/ 
heipDisplayVisibleLines (hi) ; 

for (redisplay - FALSE, quit = FALSE; ! redisplay a Iquit;) I 
(void) Mart (lL«hi->windew->DserPort->»ip SigBit); 
while (imsg = (struct IntuiMessage ■) Ge£Msg(hi->windcw-XJserPort] ) ( 

class ■ imsg->Class; 
code » imsg->Ccde; 
qualifier ■ imsg->Qualifier; 
ReplyKsgl (struct Message Mimsg); 



/* 



if the redisplay or quit flags are set, we reply to ail 
messages in the message queue, but ignore them. Once 
all the messages have been replied to, the outermost fori) 
loop will terminate. 



if (redisplay 1 1 quit) continue; 



* Neither the redisplay or quit flag is set, 

• to process this message. 

switch (class) ( 

case CL05EWIKDOW: 
/* 



IheEefoeftj we need 



* Ihe user has had enough. We set the quit flag so that 

* this loop will terminate, 

quit - TRUE; 
continue; 

case GADGBTUP: 
/' 
' The user has released the proportional gadget. We 
' probably need to redisplay the help text. 
' We need to prevent the user from resizing the window 

* until the text is redisplayed. We want to turn off 
MOUSEMOVE messages, though. 



kelp :dog> i stzevzrifvi; 



'/ 
:■::!_; ■::::■: ihi->wind:v, 
/• fall through */ 
case HOUSE.10VE: 
/• 

• If the case is MOU5EMOVE (if we didn't fall throuah 

• from the above easel we mow that the user is stili 

• playing with the proportional gadget with the left 

- mouse butter, i::>: .: : : ::.::.:.:. .:.'■■ ':.-.- ;: ; r . : ;-' 

• is in use, we K1I0H that the SIZEVERIFr option U 

• still in effect, 

• How we need to calculate the orcp gadget values (see 

• EFM) and cossibiv redisplav the text. 
'/ 

hidden - bSUS (totaiLines - visibleLines, 0|; 

■. :"-.:-- - 

( ( lULCBG) hidden ' 

( ((struct Prcplnfo ') 

|HelpProp5adoet.SpecialInfo))->VertPot|) * 

|HAXFOT/2n/nAx?OI; 

if ItonLine !- hi->tcp line) I 
hi->tco_line *■ toptine; 
heipDisplayVisibleLines (hi) ; 

break; 

case KEFRESHKISDOH: 

/* 

' since we opened a SIMPLE REFRESH window, we need to 

' handle FEFKESilwiNOQH messages. 

*/ 
BeuinRefresh (hi->window) ; 
helr-DisolayVisibleLines (hi) ; 
EndSefr'eshlhi->window, (LOIIGIIRDEI ; 
break; 

case HEHSIZE: 
/* 

• If the size of the window hasn't actually changed, we 

• have nothing to do. 
■/ 

if l(hi->win height « hi->window->Height) it 
lhi-fwin_width — hi->wlndew->width)l 
break; 



" Otherwise, we need to determine the new window 

* information. Also, since the width of the window may 

* have changed, we need to recalculate the pixel size of 

* a line. 
*/ 

hi->win height - hi->wlr.dow->Height; 
hi->pixj]er_line - RIGHTJilKGIH - LEFtKMUUH * 1; 
hi->win_tcp * hi->window->7cpEdge; 
hi->win_le'ft = hi->windcw->LeftEdge; 

/* 

* If the window width changed, we cannot just redisplay 
1 the text - we need to read it all in again. Ke set 

" the redisplay flag so that this loop will terminate. 
•/ 

if lhi->window->width !- hi->win widthl I 
hi->win_width - hi->window->width; 
redisclay - TRUE; 
continue; 
1 

/* 

* Since only the height changed we can just redisplay 

* the help text based on the new number of lines in the 

* window. We need to calculate the prop gadget values 
' again (see RKMI . 

*/ 
hi->lines per page = visibleLines - 

(BOITCM HSRGIlt - TOPJiASGIH! / Rolf HEIGHT; 
hidden <= MAX (totaiLines - visibleLines, 0) ; 
if (topLine > hidden) tcpLine = hidden; 
if (hidden > 0) ( 

vertBody - (DWORD] 

I (ULOHG) (Visiblelines-Overlap) • 
MAXBOD;/ ItotalLines-Overlap) ) ; 
) else 1 

vertlody - MAXBODY; 

if (hidden > 0) I 

vertPot = (IfflORDI (KULG1IG) tcpLine ' H.UPOTI / hidden); 
) else ( 

vertPot - 0; 
) 

JJewHodifvPropliBeipPropGadget, hl->window, bull, 
(ULOIiSIKelcP rep Info. Flags, 
-1L, (LOliGJvertEot, -1L, I LOHG] vertBody, 1L] ; 

heipDisplayVisibleLines Ihil ; 
break; 

case iSAEGETDOW::: 
/* 

* The prop gadget has been selected. As long as the user 

* keeps dragging it, we want to get H0G5EK0VE messaoes. 

* we will be redisplaying the text as the mouse moves, so 

* we don't want the user to resize the window, (it would 

* be a neat trick for the user to resize the window now 

* anyway since the prop gadget is being used!) 
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HodlfylDCHPOii-^indoK* 

(Hii= ::::3 j::e\~?.:ft !-:;jse:-::'.1i i; 
break; 

case RAWKEY: 
/* 

• The user can control the help window with the keyboard, 
" too. The following keys are available: 

• Cursor Up: Scroll up one line, 

1 Cursor Down: Scroll down one line. 

■ Shift-Cursor Up: Scroll up one page. 

• Shift-Cursor Down: Scroll down one page. 

• Alt-Cursor Up: Go to the first page of "he message. 

• Alt-Cursor Down: Go to the last* cage of the message. 
' ESC: Quit. 

'/ 
switch (code) ( 

case KELP ESC: 

quit = TRUE; 
ccntinue; 

case BEIP UP: 

tc=Lir.e-; 

if (Qualifier £ IEQ_5r:iFT] 

topLine - tcpLine - hi->lines_per_page + It 
if (qualifier s IEQ ALT) tcpLine = 0; 
if (topLine < 0) topLine = t); 
if (topLine -- hi->top_linel \ 

DispiayBeep(hi->screen) ; 

continue.* 
) else hi->tcp_line - topLine; 
brea>.; 

case ffi&P DOtWs 
tccLine++; 
if {qualifier 4 IEQ_SHIFI) 

topLine - topLine *■ hi->lines per page - 1; 
if ((qualifier & IEQALT} \\ itopEine > hidden) ) { 

tOpLinfl - hidden; 

if (topLine -- hi->top line) l 

DisplayBeeplhi->screenl ; 

continue; 
1 else hi->tcp_line - topLine; 
break; 

default: 

continue; 
\ 

if (hidden > 0) ( 

vertEody = (UWORD) 

( (ULONG) IvisibleLines-OverUpi * 
HMSOOft (totallines-Cverlap) } ; 
} else t 

vertEody * MAXBODY; 
) 
if (hidden > 0) { 

vertFot - !UW0?D) KIULO^I topLine * MAXPOT) / hidden) ; 
) else ( 

vertFot - 0; 
) 

[lewModifyprcci(iHelc?rcDGadget, hi->window, irJLL, 
(ULQNGlHeipProoInfo. Flags, 
-1L, (LCIIGlvertPot, -1L, (LQN5)vertBody, 1L) ; 

helDDispiayVIsibleLir.es (hi) ; 
brek* ; 

case SIZEVERIFY: 
default: 
f 

• Toss any other messages. 

break; 



if luuit) return (-EirEC^t ; 
return ieel? c:::t:::vej ,■ 



/ 



static void heipDisplayVisibleLines (struct Helplnstance *hi| 

Description: This function will display all lines that fit in 
the help window, starting with the top line 
specified in Helplnstance structure. 

!?!NCTE!!! The help windcw's EKHP flags mat have the 

SIZEVERIF? Flas set before this function is called! 
Otherwise, it is possible that this function will 
trash the window borders. 

Inputs: hi: a pointer to the Helplnstance data structure. 

Returns: Nothing, 

static void helpDisplayVisibleLines(hi) 
struct Kelp Instance 'hi; 

struct HelpLinelndexStruct *hli; 
uskgrt lineindex, count, endcount; 
UBYTE which hli, hold; 
struct RastPort *rp - hi->window->PPort; 

■ As a precaution, we won't reader into the window if the window width 

■ has changed since the Helplnstance structure was last updated. This 

• function KU5T be called with the SI2EVERIFY flag turned en for the 

■ window's IDCM?ort . That wilL prevent the window from being resized 

• vhiie we're in this routine. 
*/ 

if (hi->win width -- hi->window->Kidth) ( 
/* 
* First we will clear the help test area ir. the window. 



SetAPenlrp, 0L|; 

SetDrMdfrc, JMtt)i 

RectFilltrp, (LONG)hi->windaw->SorderLeft, 
{L0NG)hi->winticw->3order7cp, 

(LONG) (hi->wir.dow-> Width - hi->windov->BorderRight - 1) ■ 
(LONGI (hi->wir.dow->Height - hi->window->3crderBottam - l))j 

■ There may several line index tables. He need to find the 

* line index that points to the segments for the top line we are 

* to display. When the far() loop is dons, hli will point to the 

* correct HelpLinelndexStruct, 

which hli - hold - hi->top line/MAX LllilS PER INDEX; 

for (n"li = hi->firstlfldexi whichjili > 0; nli ■ hli->next, whichjiii-}; 

/* 

* endcount is one more than the number of lines we are to display 

* in this window. 
*/ 

endcount - MiM(hi->lines_perj:age, hi->total_lines - hi->tcp_Iine) t 

*■ Here we disolay the lines. We cay cross into other line indexes. 
*/ 

for (count - 0, lineindax = hi->top_line - (hold) ♦MAX_LINES_?ER_niDEX; 
count < endcount; ) 1 
if (lineindex — kaX_LINES_per iijdex) { 
iineindex * 0; 
hli - hli->next; 
continue; 

HOVeirp. LEFT_MARGIN, TOP MWGIH + ROWHEIGHT'count) ; 
helpDisplayLine(hi, hii->Tine[lineindex] ) ; 
ccunt ■ - ; 
lineindex++; 



static void heipDisplayLinelstruct Helplnstance 'hi, 

struct HelpSegnentStruct 'segment) 

Description: chis function displays a single help text line in 
the help window, ' it assumes the graphics cursor 
has already been MoveD'ed to the correct place. 

HIN07E!!! The help window's IDCMP flags must have the 

SIZEVEKIFY Flag set before this function is called! 
Otherwise, it is Dossible that this function will 

trash the window borders. 



Inputs: 



Returns: 



hi: a pointer to the Helplnstance data structure, 
segment: a pointer to the current segment. 

Nothing , 



static void heipDispiayLinelhi, segment) 

struct Helplnstance *hl; 

struct HelpSegr:entStruct 'segment; 

struct Help5agmentStruct •hs; 

struct RastPort *rp - hi->windcw->R?ort; 



/* 



*/ 

for 



For every segment in this line, set the softstyle, drawing mode and 
pens to the segment values and print the text . 

(hs^segmant; hs; hs=hs->next) { 

SetSoftStyle (rp, hsoscftstyle, hs->softstyle_enable) ; 

SetDrMd(rD r hs->drawmode) ; 

SetA?en(rp, hs->frontpen) ,- 

SetBPen(rp P hs->backpen) ; 

Text(rp, hs->buffer, (LCKG)hs->cursor) ; 



static void sw err (char *file, int line, char *func, ULCNG re, 
struct Helplnstance *hi) 

Description: A simple debugging function. When the UCHECKU 
macro is called, this function gets called with 
the filename, line number and function name where 
the UCKECKO macro was invoked, sw err() also is 
passed a result code that is specified by the 
caller of UCKECKO . This function will tree all 
resources allocated by the help utility and then 
exit. MOTE that any resources allocated prior to 
calling help!) will NOT be freed. This function 
should never get called. It is left in for 
debugging purposes only. 

Inputs: file: a null terminated ASCII string, representing 

the filename where the bug occured. 
line: the line number of the buggy line in the 

file, 
func: a null terminated ASCII string, representing 

the function name where the bug occured. 
re: a value that is meaningful only in context of 

the buggy line, 
hi: a pointer to the Helplnstance data structure. 

Returns: Nothing. Actually, it terminates the program. 
Read the description above. 



static void sw err (file, line, func, re, hi) 

char 'file, »func; 

int line; 

ULONG re; 

struct Helplnstance *hi; 

printf rsv^err: ta:td:ts tc=Ux(Ud) Vn", 

helpFreeAlHhU; 
exit (re) ; 



file, line, func, re, re} ; 
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Programming 
the A m i # i\ GUI in C 

•Parti • 



by Paul Castonguay 



This is the beginning of a series that will help you take advantage 
of many of the custom featuresof your Amiga using theC Programming 
Language, In this issue you will find: 



u 



2.) 



3.) 

4.) 

5.) 



6.) 



A description of the skills that you will need in order to 

program your Amiga in C, 

A detailed installation procedure (on disk) of the SAS version 

5.Wa compiler for Hard Drive as well as Floppy systems. The 

installation of51ZK, 1MB, as well as 2MB "Two Floppy 

Systems" is optimized by special installation programs. 

Some background material (on disk) for understanding 

compilers and linkers. 

An overview (on disk) of the SAS/C environment. 

A detailed descript ion (on disk) of how to use SAS/C, complete 

with an example program to test the validity of your 

installation. 

A presentation (in this article) of the first programming 

concept in the Intuition environment, theopeningoj libraries. 



The example program (on disk) is called Rosettes and it 
demonstrates the kind of programs I intend to present through- 
out this series. It is not so complex that it will seem impossible to 
learn, yet hopefully it is interesting enough that you will want to 
find out how to write similar programs yourself. It should at least 
convince you that you can indeed design, compile, and execute C 
programs that interact with the custom features of your Amiga, 
even on a 512K two floppy system. 

SAS/C Version 5.10a 

This is the compiler that I will be using. If you have pur- 
chased the recent 5.1 0, please be advised that you are now eligible 
for a free update simply by calling the "Book Sales Department" 
o f S AS a 1 91 9-677-8000, ex tension 5042 and giving them your user 
registration number. In fact, if you have a 'Two Floppy System" 
you may ha ve had trouble getti ng vers ion 5 . 1 of SAS/C to work 
on it. There were some simple but unfortunate errors in their 
"read.me" file that made it difficult for an uninitiated, first time 



user to successfully install the product on a floppy system. The 
new version 5. 10a has corrected them. Inaddition, the installation 
programs and valuable background material in this issue of AC's 
TECH (on disk) will just about guarantee that you not only get 
SAS/C up and running, but also configure it in a way that takes 
maximum advantage of your system. There are in fact three 
separate installations for three different sizes of 'Two Floppy 
Systems," 51 2K, 1MB, and 2MB. 

WHYC? 

C is the most natural high level language to program the 
Amiga with. Many of the Amiga's system functions expect to be 
called in a form that is easily implemented in C. But as an average 
hobbyist, you may be feeling a bit overwhelmed by the apparent 
complexity of such programs written for the Amiga. Even if you 
have already taken a C programming course, you may be unsure 
of how to apply that knowledge. Just the simple act of opening a 
graphics window may look at first like a formidable program- 
ming challenge. 

Successful programming in C is largely a matterof organizing 
your wo rk so that it is useful in the grea test number of situa tions . 
A program fragment that performs a particular task, like opening 
a window, should be written in such a way that it becomes useful 
to any programming projects that need one. In this series I will 
emphasize techniques to help you do that. Naturally you will 
need some prerequisites and I will list them in the next section. 
But even without them you should have no trouble following the 
detailed instructions on disk and getting your compiler up and 
running, even compiling the Rosettes program. 

PREREQUISITE #1, LEARN TO USE YOUR COMPUTER 

You need to know how to do such things as make backup 
copies ofyoursystemdiskettes, run programs, initialize (format) 
diskettes, produce documents using either a word processor or 
editor, organize your work into drawers (directories), ... etc. 
These operations and many more are generally referred to as 
"using your computer at its system or command level." You 
cannot seriously sit down to program a computer in any language 
unless you know how to do that. 
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The Amiga has two modes of operation at the system level, 
the interactive icon /pull-down menu mode, available from the 
Workbench tool (applica tion), and the command line mode called 
AmigaDOS available from the SHELL window. You should 
develop the skill of using both. You may accomplish this quickly 
if you have had previous experience on other systems, or not so 
quickly if the Amiga is your first computer. Whatever your pace, 
don't rush it. Learn to use your computer comfortably. 

I'd like to also add that although the Workbench tool seems 
to need no explanation, don' t underestimate its powers. Read the 
manual. For example many users complain that it is too clumsy 
when duplicating a series of diskettes on a two-drive system 
because it requires a disk-swap each time to pick up the DiskCopy 
program from the boot-up diskette. Not so. The DiskCopy pro- 
gram can be operated from the RAM Disk using icons. Here is the 
procedure: 

L) Open the Workbench/System window and drag the 

DiskCopy icon to RAM: 
2.) Open the RAM: window so that the DiskCopy icon is 

visible. 
3.) Place the diskette you wish to back up in any drive and 

a blank one (or otherwise not needed) in the other. 
4.) Left-select the disk you want to back up. 
5.) Press the SHIFT key and hold it down throughout the 

remainder of this procedure. 
6.) Left-select the destination disk. 
7.) Double-click the RAM:DiskCopy icon. You may now 

lift the SHIFT key. The DiskCopy procedure continues, 

presentingyou with the usual dialogue box and without 

any swaps. 



Getting starting in programming 
the Amiga in C... 

Including a presentation of the first 
programming concept in the Intuition 
environment, the opening of libraries. 



Thus you may conveniently back up a series of diskettes, like 
the ones that came with your SAS/C Compiler. Note that this 
procedure changes their names from "SAS_C_5.1 .X" to "Copy of 
SAS_C_5.1.X," a feature that is very desirable when backing up 
your own work. How often have you forgotten which disk was 
the original and which was the backup? The above feature saves 
you the trouble of looking inside each disk and comparing date 
stamps on the various files to find that out. But if you want to use 
the above disks to install SAS/C on your system you will have to 
change their names back to "SAS„C_5 J.X." 

For those who want to learn AmigaDOS I recommend the 
latest editions of either "COMPUTE'S AmigaDOS Reference 
Guide," by Arian R. Levitan and Sheldon Leemon, Compute! 
Publications, Inc., 1986, or 'The Amiga Companion," by Rob 
Peck, I DGC/ Peterborough Publications, 1988. In addition to 
learning all the usual commands for copying files, creating di- 
rectories, and organizing your work, you need to understand the 
assignment o f logical devices. Make sure you know what is meant 
by a system logical device, like C:, S:, LIBS:, FONTS:, and SYS:, as 
well as user defined logical devices. For example: 



Assign BK; My_Work:My_C_Progs/Windaw_Examples 

This command assigns the device name BK: to a directory 
where you would like to save your work. The device name BK: is 
a convenient way of specifying that location. Suppose, for instance, 
your current working directory is a drawer on the RAM Disk, as 
is usually the case in SAS/C for smoothest operation. You can 
backup your work with the simple command: 

Copy #? to BK: 

The system will automatically ask you to insert the 
"My_Work" disk, and then copy all files from your current 
directory to the above specified location. 

The assigning of logical devices cannot be done from the 
Amiga's Workbench tool, although you can design the feature in 
by using the IconX program in conjunction with a script file and 
an icon of your own design. 
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UPDATE 

on disk in update, lzh 



FastBoot DBI Idiosyncrasies (AC'S TECH 1. 1) 

Some readers have been experiencing some problems with 
the DBI program included for use with the FastBoot story in 
AC's TECH VI. 1. We have included a fresher copy of the DBI 
program on the AC's TECH 1.2 disk (Included in Updates.lzh). 
We hope this solves any problems you may have encountered. 
Thanks to the readers who brought this to our attention.An 
additional thanks goes to Dan Babcock for his help. Also, 
please note that DBI is shareware. If you find DBI to be useful, 
please send the nominal $5.00 shareware fee to the author, 
Jorgen Kjaesgaard. His address is listed in dbi.doc. 

VidCell Digitizer Questions (AC's TECH 1. J) 

Oops! We incorrectly listed the Digi-Key part number for 
the high-speed 555 timer in the VidCell digitizer story. The 
correct part number is LM555CN. If you have a hard time 
locating that part, use ICM7555IPA, which is also available 
from Digi-Key. 

Additionally, some readers have reported some difficul- 
ties in locating the KAD0820BCN A/D converter. Digi-Key 
reportedly does not stock that part any longer. Another 
verified source is Allied Electronics. Their order number is (800) 
433-5700. Many thanks to Doug Austin for this information. 
Jameco sells a verified equivalent A/D converter, 
ADC0820CCN, for $12.00. Jameco's number is (415) 592-8097 
Please note that Jameco enforces a $50.00 minimum order. In 
any case, if you prefer you can purchase the A/D converter 
directly from GT Devices for $12.00. 

There were also minor errors in the schematic drawing on 
page 28.The polarity symbols (+ -) at C4 should have been 
reversed. If you follow the schematic sysmbol, you'll be fine. 
Thanks to Alastair Bor for pointing out this problem. 

Finally, due to popular demand the VidCell PCB only is 
available from GT Devices, for $20.00. For more information on 
VidCell, or to order, write to GT Devices, P. O. Box 2098, Pasco, 
W A, 99301. 



Where's SuperView? (AC's TECH 1. 1) 

Some readers have commented on the empty 
superview.docs directory which was accidently left on the AC's 
TECH 1.1 master. SuperView was never meant to appear on 
the AC's TECH disk, so you didn't miss a thing! 

Missing ARexx? (AC'S TECH 1. 1) 

The lharc file for 'An Introduction to Interprocess Com- 
munication with ARexx' on the AC's TECH Disk 1.1, was 
accidently omitted from a master diskette. We have included 
the file as IPC. lzh. We apologize for the error. 



Please let us know if you make any major upgrades/ 
modifications (for the better!) to any of the software/hardware 
projects that appear in AC's TECH. We will send a copy of 
your changes to the author, and maybe even distribute it via 
AC's TECH Updates. 



Send your comments, suggestions, and program updates to: 

PiM Publications, Inc. 
AC'S TECH UPDATES 
P.O. Box 869 

Fall River, MA 02720-0869 
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Presenting the 

AC'S TECH Disk-Volume 1 , Number 2 



A few notes before you dive into the disk! 

• You'll need a working knowledge of the AmtgaDOS CLI as most of the files on the 
AC'S TECH disk are only accessible from the CLI. 

• In order to fit as much information as possible on the AC'S TECH Disk, we archived 
most of the files using the freely redistributable archive utility 'lharc' (which is 
provided in the C: directory), lharc archive files have the filename extension .Izh. 

To unarchive a file foo.lzh, type lharc x too 
For help with lharc, type lharc ? 



THE Ar'cTr C n disk 
GOES HERE! 




We piidc ourselves on the quality of our p^ni 
cr,d magnetic media publications. However, in 
the highly unlikely eveni cf a faulty or dam- 
aged disk, please return the disk to PiM 
Publications, Inc. for a free replacement, 
at the following address: 

ACs TECH 
Dak ^coiccement 
P.O. Box8q9 • 

Fa" ™ver. VIA 02720-0869 



HAPPY 
PROGRAMMING! 

ENJOY! 



CAUTION! 

Due 10 the technical and eapeiimeriial nature of some of 
itie programs on the AC'J TECH Disk, we advise the 
reader to use caution, especially when using 
experimenial programs that initiate low-level disk 
access. The entire liabil it> of the quality and 
performance of the software on the /JO TECH Disk is 
assumed In the purchaser. PiM Publications. Inc., their 
distributors, and/or its retailers, will not be liable for 
any direct, indirect, or consequential damages resulting 
from the use or misuse of the software on the ACs 
TECH Disk. (Ttiis agreement may not apply in all 
geographical areas.) 



Although many of ihe individual files and directories on 
the Ad TECH Disk are freely redisiribuiable. ihc 
ACs TECH Disk itself and the collection of individual 
files and directories on the AC's TECH Disk are 
Copyright ©1990. | W| by PiM Publications. Inc. and 
may not be duplicated in any way. The purchaser, 
however, is encouraged lo make an archive/backup 
copy or the ACs TECH Disk. 

Also, be eilremely careful when working with 
hardware projects. Check your wort: twice, lo avoid any 
damage thai can happen. Also, be aware thai using 
these projects may void the warTamies of your 
com purer equipment. Neither PiM Publications, nor its 
agents will be held responsible for any damages 
incurred while attempting these projects. 



PREREQUISITE #2, LEARN BASIC 

That's right, I recommend that before learning to program 
your Amiga in C, you do so in BASIC, I give this advice to both 
novice and experienced programmers alike, although to each for 
different reasons. 

Beginning programmers need to learn the fundamental con- 
cepts of programming, the standard building blocks (constructs) 
around which all programs are built, regardless of language. 
BASIC allows you to do that within an environment that is easy 
to u se. I a lso recommend True B ASIC becau se i t is a compiler, and 
because it supports many of the concepts tha t are usually attribu ted 
to C, like local variables, external functions, library files (similar 
to header files and pre-compiled modules in C), and recursion. It 
also allows access (through the Toolkit) to the same system 
functions tha t we will be using here in C. And most important for 
beginners, True BASIC is a well-established teaching language 
with excellent textbook su pport. 1 1 wi 11 help ease your graduation 
toC. 

Experienced programmers, even experienced C program- 
mers, need to become familiar with the machine they are pro- 
gramming, and most importantly its display. You can't create 
much of a program if you can't show anything on the screen. 
Amiga BASIC is an easy-to-use environment that supports the 
underlying concepts of screens and windows. Play around with 
the SCREEN and WINDOW statements. Find out about bitplanes 
and how they are used to produce 32 colors. Try a few simple 
graphic images. You don't have to devote a lot of time and energy 
to this, just enough to make yourself feel comfortable with how 
the system works. An excellent text is "Advanced AmigaBASIC," 
by Tom Halfhill & Charles Brannon, COMPUTE! Publications, 
Inc., 1986. Often, when you are about to try a feature on the Amiga 
for the first time in C, it is informative to see first how that same 
thing is implemented in AmigaBASIC. 

PREREQUISITE #3: LEARN STANDARD C 

Standard C is the language that you learn in a C program- 
ming course at any community college or university. (Anyone 
questioning my use of the term "Standard C" should refer to the 
editorial in the January, 1991 issue of 'The C Users Journal," R&D 
Publications, Inc. 2601 Iowa, Lawrence, KS 66046, (913) 841- 
1631). The syntax of Standard C is in accordance with the now 
famous book 'The C Programming Language, Second Edition," 
by Brian Kemighan and Dennis Ritchie (the creators of the C 
Language), Prentice Hall 1988, which I refer to throughout this 
series as K&R. However, if you've never studied C before and if 
you're trying to do so on your own, you may prefer an easier text. 
A good one is "C Primer Plus," by Mitchell Waite, Stephen Prata, 
and Donald Martin, Howard W. Sams & Co., 1985. Buy the latest 
edition. 

Note that Standard C doesn't interact with the Amiga's 
system of graphic windows, menus, sprites, etc. Rather it is 
limited to treating the computer as if it were a plain, vanilla-type 
terminal (DEC VT-100 or equivalent), the kind that you see many 



of when you visit the computing center at any university. Screen 
I/O (input/output) usually consists of standard format, text 
strings within a scrolling type window. On the Amiga such 
programs use a SHELL window. It is in fact an important feature 
of the Amiga that it can run any Standard C program, with 
perhaps a few trivial exceptions, from a SHELL window. That 
means you can take any course in C and execute all your assign- 
ments righton your Amiga. Italso means you canuse your Amiga 
to learn all about C programming on your own, at home. Natu- 
rally, to do this you will have to install your compiler and learn 
how to use it. As I mentioned earlier, you can find detailed 
instructions on how to do that, along with some valuable back- 
ground material, on the disk that came with this magazine. 

THE AMIGA'S GUI, INTUITION 

In case you haven't already guessed there are really two 
ways to program the Amiga in C. The first, mentioned above, 
interacts with the system from an ordinary SHELL window. To 
make such programs accept data you use functions like: 



scanf ( w %s", unsigned char *s) ; 
getchar ( ) ; 



To make them produce output you use functions like: 



printf ("%s", unsigned char *s) ,- 
putchardnt c) ; 






Note that it is my style to occasionally show the data types of 
certain arguments in a function call by using the same form as the 
new ANSI prototype declarations. I do this whenever I think it 
will help in their u nderstanding. For example, the above "unsigned 
char *" shows you that "s" is a pointer to type "unsigned char". 
In a real program you would not use that notation for a function 
call. Rather, you would first declare s, then use it as an argument, 
alone like this: 



unsigned char *s 
printf ("%s", s); 



"Hello out there! !!\n" 



The second and more exciting way to program the Amiga is 
to interact with it through an environment called a GRAPHICAL 
USER INTERFACE (GUI) that supports the use of windows and 
pull-down menus. The Amiga's GUI is called "Intuition." 

I want to mention at this point that there are other computers 
besides the Amiga that have "Graphical User Interfaces." The 
UNIX operating system has X Windows, the Macintosh has the 
Toolbox, and IBM has Microsoft Windows Version 3.0 (and a few 
others such as HP's New Wave). The irony is that while those 
systems cancost you a lot more, Intuition on the Amiga completely 
outperforms them on similar hardware. And, the Amiga's 
windowing system multitasks without four megabytes of RAM 
and an 80386 microprocessor. 

Programming in the Intuition environment, or any other 
GUI for that matter, is very different from programming in 
Standard C. GUI's require that you become familiar with a large 
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number of functions, each of which may require knowledge of a 
multitude of details before you can use them. For example, to 
send text to a graphics window requires (but don't try to under- 
stand it yet) the function: 

Text (s truce RastPort *rp, unsigned char *s, scrlen(char *s)); 

In addition, Intuition's functions are specific to the Amiga. 
Programs written in it will not execute on a UNIX or MS-DOS 
machine and visa versa. Still the general operation of all GUI's is 
similar enough so that experience in one is an advantage when 
trying to learn another. 

The standard reference for the Amiga is the "ROM KERNEL 
REFERENCE MANUAL: LIBRARIES & DEVICES," Addison 
Wesley 1990. But any hobbyist who has seen that book knows 
how overwhelming it can be. Does that mean you have to be a 
trained computerscientist with XWindows experience to program 
the Amiga in C? Hey, the Amiga is supposed to be a hobbyist's 
machine, remember? Surely there mustbe some way the average 
user can access its great potential as well. There is, and it is the 
purpose of this series of articles to present exactly how that is 
done. Once you get up and running with a few of the basic 
concepts, you will find yourself much more able to deal with that 
ROM Kernel Manual. 

THE AMIGA'S HEADER FILE SYSTEM 

Remember from Standard C how you were required to 
reference certain files that contained definitions particular to the 
system you were using? You did that by putting at the top of your 
source code one or more #include statements (actually called 
preprocessor directives) that made reference to one of these files, 
traditionally called header files (K&R, pages 33, 88). For example: 



linclude<stdio.h> 

#inclucie<strlng.h> 

#include<math.h> 



You probably learned from experience that there were times 
when one of your programs didn't work because it was trying to 
perform an operation requiring one of these (K&R, 241). And 
perhaps at the time you didn't care what the particular problem 
really was, or what exactly was in those fifes. You just wanted 
your program to work, so you blindly added #include statements 
at the top of your source code until it did . Such an approach won't 
work on the Amiga. 

The Amiga's system of header files contains a formidable 
numberof declarationsand definitions that you mustbeawareof, 
and in some cases be intimately familiar with, in order to take 
advantage of its custom features. In SAS/C there are actually two 
sets of such files. The first, called "Compiler Headers," is located 
in the directory SAS_C_5.1.4:CompiIer_Headers, in dhO:LC/ 
CompilerJHeaders on a hard drive system. These files are for 
reference. They are for you to inspect and study whenever you 
need to know aparticulardetailabout some fea hire of the Amiga . 
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The second set is called "Compacted Header Files." These 
are the exact equivalent of the others except that they have been 
compressed in size for faster access. They were produced from 
the first when you installed SAS/C on your system and they are 
located in the INCLUDE: device. These "Compacted Header 
Files" are for your compiler to read. They are referenced when 
your program is compiled. 

To get a printout of the names of all the header files that come 
with SAS/C, enter the following command from a SHELL win- 
dow: 

Dir >PRT: INCLUDE 1 OPT A 

The Amiga's header files fall into two main categories. Those 
in the first, which I call "Standard Headers," are the same as those 
that you will find on any implementation of Standard C. They 
have the familiar names: <stdio.h>, <string.h>, <math.h>, etc. 
(K&R, 241) The second category of header files is what I call 
"Amiga Specific Headers." These contain a proliferation of defi- 
nitions and details that have to do with the Amiga's custom 
features. 

A large part of the secret to programming the Amiga is in 
becoming familiar with what is in these files. I will slowly begin 
to do that in these articles. Notice that many of them are divided 
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into directories with names like: exec, intuition, and graphics. 
Each contain files that are used to access a particular part of the 
Amiga's operating system. The particular header files that allow 
the use of the Amiga's GUI are in the directory called "intuition". 
Butbefore getting into that, we need to consider some fundamen- 
tal concepts. 

AMIGA'S DATA TYPES 

Your first job in programming the Amiga is to become 
familiar with its data types. You know that in Standard C all 
variables must have their type declared: 



int i; 

unsigned char *str; 

float :•:,- 



But perhaps you have seen listings for the Amiga in various 
magazines that referred to following data types: 



uwosd i; 
STRPTR str; 
FLOAT :<; 



These are simply new names for some of the usual data types 
of Standard C. They are in fact the exact equivalents of the first 
three that I just mentioned. 

These redefinitions are made for you by a series of "typedef" 
statements (K&R, 146) in the header file <exec/types.h>. So to 
become familiar with the Amiga's data types you must look at 
that file. You can do that by using your editor. Enter into a SHELL 
window: 

LSE SAS_C_5.1.4:Compiler_Headers/exec/ti'pes.ti 

You will also find there some macro definitions (K&R,88) for 
the storage classes extern (K&R,31, 33, 80) and register (K&R,83). 
You are not forced to use these definitions. After all, the compiler 
itself must first perform the proper substitutions and convert 
them all back to Standard C before compiling your program. 
However, t here a re cer ta in advantages to usi ng them. They make 
your programs more understandable. Here is a short example: 



#include<exec/types . h> 
main ( ) 

! 

STRPTR s_one, s_two; 

s_one = "Hello out there! l!\n"; 

s_two ■ "Help me I'm stuck in hereAn"; 

printf ("%s%5", s one, s_two) I 



Note that STRPTR is defined in <exec/ types. h> as "un- 
signed char *". In the above example the name STRPTR is more 
informative than "unsigned char *" because it identifies not only 
that s_one and s_two are pointers of type char (which can point 
to any location in memory), but also that your intention is to use 
them specifically to point to strings. Strings are contiguous sec- 
tions of memory containing text and terminated by a "null 
character" (K&R, 30). 



All this may seem like a lot of talk over a minor point, but it 
isn't. You see, the Amiga is so complex a machine that knowing 
the exact purpose of a variable is often crucial to understanding 
how a program works. In fact, here lies another large part of the 
secret to programming the Amiga in C. You must write your 
programs in such a form that they not only work, but also that 
they are easily understandable to yourself and others. Thus 
<exec/types.h> is an important inclusion for all your programs. 
But later we will see that its inclusion is automatic when we 
include a certain other header file. 

THE AMIGA'S RUN TIME LIBRARIES 

In most programming environments your compiled pro- 
grams are linked to whatever system routines are needed to run 
them. The Amiga does that with its "Startup Code" and "Standard 
Math Library," and in that way it is no different than any other 
system. But the Amiga also allows your programs to use other 
libraries that are not linked to them. Indeed, these libraries are 
loaded onto the system independently of your programs and are 
called "Run Time Libraries." The idea is that the system needs to 
put only one copy of such a library in memory and it will serve the 
needs of several programs running simultaneously. You can see 
immediately that the Amiga was designed as a multitasking 
machine from the ground up. In fact, the Amiga has several of 
these "RunTime Libraries," each of which is loaded into memory 
only if a program running on the system requests it. We will be 
using several "Run Time Libraries" in this series. 

The particular "Run Time Library" that is related to the 
Amiga's GUI is called "intuition.library". Thus the first operation 
that any of your programs must do (to use the GUI) is send a 
request to the operating system asking that it load 
"intuition.library" into memory (open it). This is done by calling 
the system function "OpenLibrary( )." 

THE EXEC IS ALWAYS THERE 

The "exec.library" is another "Run Time Library," but unlike 
"intuition.library" this one is always loaded on the system. It 
happens automatically at boot up time. The "exec.library" con- 
tains many low level, system functions for the Amiga, but we 
need to know only a few of them. It turns out that a lot of the use 
of the various functions in "exec.library" will be hidden from us 
by the fact that they a re often called directly by functions in other, 
higher level libraries. Thus we will be protected from many of the 
computer's lower level details. This is in accordance with a formal 
principle in computer science called "Information Hiding," which 
dictates that different programs, indeed even different parts of 
programs, should not have any unnecessary knowledge of each 
other. This principle reduces the complexity of our own pro- 
grams by lowering the number of details that we must be aware 
of in order to design them. 1 will refer often to this principle in 
these articles. 
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OPENING A LIBRARY 

Here is what we must do within our programs to request 
"inruition.library" from the operating system: 

1 .) Declare a pointer (K&R,93) of the correct type. The 
"inruition.library" has its own special type of pointer 
that you must use, 

2.) Call the OpenLibrary( ) function using as arguments the 
name of the library and a version number. The function 
will return to us the address in memory where it 
successfully loaded the library, or a NULL if it failed. 

3.) Test that the library was successfully loaded into 
memory. 

4.) Assign the address of the library, as returned by the 
OpenLibrary( ) function, to the previously declared 
library pointer. 

THE LIBRARY POINTER 

There are two design considerations that affect how you 
should declare the library pointer. First it must be available to all 
sections of your program that need to use functions in the library. 
Second, reference to it is handled automatically by the system. 
That is, you yourself don't need to use the library's address as an 
argument in any of your function calls. You simply call a function 
by name and the system finds it for you. To be able to do all this 
requires that this pointer be of global scope (K&R,80) and of a 
particular type and name. In this case the type must be "pointer 
to struct InfuitionBase" and the name must be "IntuitionBase." 
And be careful, these names are case sensitive. Remember from 
Standard C that a structure is a data type that can contain items 
(called members) of different types (K&R, 127). 

So, touse the OpenLibrary ( ) function your program requires 
the following global declaration: 

struct IntuitionBase "IntuitionBase; 

Well now, if that doesn't sound like a lot of double talk, I 
don't know what does. Actually it's very simple. First of all, the 
type "struct IntuitionBase" is data type that is declared for you 
within the header file <intuition/intuitionbase.h>. You can look 
there and inspect its details if you like, but it isn't necessary that 
you know much about it. You will not be called upon to make any 
references or assignments to any of its members. The system will 
do whatever is necessary for you, automatically. However you 
should realize that this structure does not come magically out of 
the clouds, but is in fact declared in the header file <intuition/ 
intuitionbase.h>, which somehow must get included with your 
program if you ever want to use "intuition. library." 

VERSION NUMBER 

The version number represents the release of the operating 
system you are using. There is a macro definition (K&R,89) in 
<exec/types.h> called LIBRARYJVERSION which gives you the 
version number of the operating system that your compiler is 



presently supporting. The actual version of the operating system 
you are using is available either from a Workbench menu selec- 
tion, or by entering into a SHELL window the following 
AmigaDOS command: 



version 

My system reports: 

Kicicstart version 34.5. Workbench version 34.20 

Version numbers are there for your protection, but it is also 
your responsibility to verify tha t you are using the correct one. I f 
you use a version of the compiler that is higher than that of the 
system, you could get into trouble by accidentally using some- 
thing that is not yet supported on your computer. On the other 
hand, a compiler that is lower than the operating system may not 
be able to take full advantage of everything available on the 
computer. You should look into <exec/types.h> and compare 
your compiler's version number against the one reported by the 
above "version" command on your system. 

The OpenLibrary( ) function protects you against any dan- 
gerous incompatibilities between different versions of the oper- 
ating system by refusing to open a library if you give it a version 
number that is higher than the one on the system where the 
program is running. In a minute we will write a program to 
investigate this, but first I must talk about how the SAS/C 
compiler links programs that use the Amiga's custom features. 

PROTO HEADER FILES 

In older versions of the compiler (from Lattice) when your 
programs made use of any operating system functions, it was 
necessary to link them to a certain library file called "amiga.lib" 
(page Gl of your SAS documentation). But recently it has been 
possible to bypass that requirement by using within your pro- 
grams certain include statements for what are called "Prototype 
Header Files." There are some 19 of these files and they serve two 
purposes. First, they declare all the Amiga's system functions 
according to the new ANSI standard (K&R, 26). Second, they 
allow the system to call these functions more directly than was 
possible before, without the need to link to "amiga.lib". SAS 
claims that including these "Proto Header Files" improves the 
execution speed of your programs while also reducing the time 
required to link them. I also noticed that it takes less memory to 
link programs that include proto files, an important issue on a 
51 2K machine. I will therefore use the "Prototype Header Files" 
in all my example programs in these articles. 

Note that the floppy installation procedures (on disk) do 
NOT install the file "amiga.lib" to the SAS_Headers diskette. I do 
not recommend it (and neither does SAS) because doing so will 
make the SAS_Headers diskette 100% full, as opposed to 89%. As 
a programmer you will want some of that room for your own use. 
As a result, if you try to compile and link programs that use any 
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of the Amiga's "Run Time Libraries" you should have in your 
code an inclusion to the "Prototype Header Files". Without it the 
Linker will report: 

Error 425: Cannot find library LIB:amiga.lib 



Compile, link, and run the program each time. When the 
function call fails you will get something like this: 



The LIBRARY_VERSION Is 34 

The address of intuition. library is 



LAZY MAN'S PROTO INCLUSION 

If you are trying to compile someone else's code, and are not 
sure which system "Run Time Libraries" the program is using, 
you can include the single file <proto/all.h>. This will cause the 
inclusion of all prototype declarations for all the Amiga's "Run 
Time Libraries". The program will then link without "amiga.lib" 
no matter what. 

TESTING THE OPENLIBRARY( ) FUNCTION 

Ok, now it's time to try out our first function call to the 
Amiga's operating system. But let's take a conservative ap- 
proach. Here is an example which simply asks the system to load 
the intuition library and then report its address. It also reports the 
version number of the operating system that your compiler is 
supporting. The example will give you a chance to experiment 
with the OpenLibrary{ ) function. 



Sinclude<e2!ec/types .h> 

Hlnclude<intuitlon/intuitionbase.h> 

# include<prot o/exec . h> 

t I nclude<proto/ intuit ion. h> 

struct IntuitionBase ^IntuitionBase; 



:nain( ) 
I 

IntuitionBase 



(struct IntuitionBase *) 



OpenLibraryC'Intuitlcn. library", LIBRARY_VERSIOM! : 
printf ("The LIBRAKY_VERSION is *d\n", LIBRARY_VERSION) ; 
crintf ("The address of intuition. library is %u\n", IntuitionBasel ; 

} 



That above program on my system reports: 



The LIBRARY_VERSION is 34 

The address of intuition, library is 12598564 



Note that this program should be run from a SHELL win- 
dow. If you run it from an icon it executes and closes its window 
faster than you can read it. 

Now, here is some homework for you. I want you to try the 
following experiments. 

1 .) Change the first letter in the library name to uppercase 

letters, like this: "Intuition.Library". 
2.) ChangetheversionargumentfromLIBRARY_VERSION 

to the number 0. 
3.) Change the version argument to the number 50. 
4.) Remove the cast {K&R, 45) from the function call. That 

is, change it to the following: 

IntuitionBase = OpenLibraryC'intuitlon, library", LIBRARY_VERSION) ; 



Make sure you understand what makes the function fail and 
wha t al lows it to succeed . The name of the library is case sensiti ve. 
"Intuition.Library" causes the function to fail. Notice also that it 
fails whenever you specify a version number higher than the 
operating system you are using. Finally, notice how the compiler 
gives you a warning whenever you leave out the cast statement 
from in front of the function call. 

Were you brave enough to ignore the warning and try 
running the program anyway? It runs normally. So why the 
warning? The answer lies in the prototype declaration of the 
OpenLibrary( ) function in the <proto/exec.h> header file. The 
function is declared as type "pointer to struct Library" and we are 
assigning it to a pointer of type "pointer to struct IntuitionBase". 
The "intuition.library" has its own personal data type that we 
must point to. The compiler notices that these data types are 
different and alerts us to the possibility of an incompatibility. 
Basically the compiler is saying, "Hey buddy, do you know what 
you're doing?" 

It turns out that we do know what we are doing, and we use 
the cast statement to let the compiler know. Basically we are 
saying "Yes buddy, 1 do know what I'm doing, so stop sending 
this particular message." But of course you do not want the 
compiler to suppress all such error messages completely, only in 
this instance. You still want it to report other occurrences of this 
same kind of error if they occur elsewhere in your program. 
Perhaps somewhere else in your program you really did ma ke the 
mistake of assigning an address to an incorrect pointer type, and 
if so you certainly will want the compiler to save you from any 
possible disasters. 

It is a common theme throughout your work on the Amiga 
that a cast statement is used whenever you must assign a value 
returned by a function to a variable whose type is different from 
that of the function. And of course, you really must know what 
you are doing. 

VERSION NUMBER PROTECTION 

If you compile and run a program on your own computer it 
is easy to make sure you have the latest versions of both the 
operating system and compiler. In my case both are 34. But what 
happens when you give a copy of a program created on your 
machine to a friend, who, for one reason or another, is still using 
AmigaDOS version 1.2, Quite simply, your program will not 
work. The OpenLibraryO function will detect the incompatibility 
and return a NULL address. But be careful! If at that point your 
program was to try to use a function within that library the 
machine would then crash. 
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It is your responsibility as a programmer to design your 
programs such that they do not use functions in any library that 
for one reason or another cannot be successfully opened by the 
operating system (otherwise your friends will have you sent to 
remedial programming school for crashing their machines). The 
solution is simple and from your experiments with the above 
example you have probably already guessed it. Your program 
must test the value returned by the OpenLibraryC ) function. If it 
is zero (NULL), your program should exit safely, otherwise it can 
assume that the library is present and go ahead with normal 
execution. 

Pictures (flow charts) often help solidify yourunderstanding 
of programming operations. In that spirit I offer the following 
personal depiction of the opening a "Run Time Library" (see 
figure one.). Here is our previous example modified to do that: 

#include<exec/types . h> 
#include<intuition/ intuit ionbase.h> 
#include<proto/exec . h> 
♦include <proto/ intuit ion . h> 
*define INTUIT ION_REV 33 

struct IntuitionBase ^IntuitionBase; 

main ( J 
I 

IntuitionBase ■ (struct IntuitionBase *) 

OpenLibrary ("intuition. library", INTUITIONREV) ; 

printf("The LIBRARY_VERSION is %d\n", LIBRARY_VERSION) ; 
printf ("The address of intuition, library is %u\n", IntuitionBase) ; 

if (IntuitionBase == NULLI 

1 

printf("The intuition library could not be found. \n"l; 

printf("Your program must exit safely, \n"); 

exit (1); 



printf("You got the library. \n "); 

printf("You may continue normal program execution . \n") ; 

return (0); 
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You may notice that even though you inform the operating 
system that you no longer need a library, it may not actually get 
purged immediately. The operating system has its own list of 
priorities to take care of and it may decide to hang on to it for a 
while. But regardless of what the system decides to do, the point 
is that unless you report when your programs are finished with 
certain resources the system will never be able to clear them up 
later when it needs to do so. 



The above program protects the code from crashing on older 
Amigas. To do this you must specify the version number used in 
the open library function call. Commodore reccommends version 
33. (See RKM page 231.) I will do this from now on. 

CLOSING LIBRARIES 

A constant theme on the Amiga is that resources are loaded 
into system memory only when they are needed and later purged 
if they are not. Thus, it is your responsibility as a programmer to 
report to the operating system whenever one of your programs 
no longer needs a resource. For a "RunTime Library" you do that 
by calling the Close Libra ry( ) function. It takes one argument, the 
same pointer that you used to open the library with in the first 
place. In the present situation this calls for the following: 

CloseLibrary ( (struct Library *) IntuitionBase) ; 

A cast statement is needed in front of the argument in the 
above call because the data type of IntuitionBase differs from the 
one given in the prototype declaration in <proto/exec> for the 
CIoseLibrary( ) function. 



STRUCTURED PROGRAMMING 

Perhaps you are now realizing that the simple act of opening 
a library has a lot of details surrounding it. Earlier I mentioned 
that a lot of C programming is based on properly organizing your 
work such that it becomes reusable in many different program- 
ming projects. You don't want to spend a lot of time writing the 
intricate details of opening libraries every time you start a new 
project. You want this operation to be streamlined, requiring no 
more than a very few lines of code. You want it to be both easy to 
use and easy to remember. Take a look at the following modifi- 
cation to our little example: 



#include<exec/types .h> 

#include<intuit ion/ intuit ionbase,h> 

#inciude<pr3to/exec.h> 

# inciude<proto/ intuition . h> 

tdefine INTUIT10N_REV 33 

struct IntuitionBase *IntuitionBase = NULL; 
BOOL 0pen_Libs(VOID) ,- 
VOID Close Libs (VOID); 



maind 



if (LOpen_Libs ()) 
exit (1) ; 



Volume 1 , Number 2 



57 



printf ("The address of intuition. library is %u\n", IntuitionBase) ; 
Close Libs(); 



) 



BOOL OpenLibs (VOID) 



1 



if ( ! (IntuitionBase = (struct IntuitionBase *) 

OpenLibrary ("intuition, library", INTUITION_REV 33))) 
( 

printf ("intuition. library could not be loaded. \n") ; 

return (FALSE); 
) 
return (TRUE) ,- 



VOID Close_Libs(VOIDI 

■; 

if (IntuitionBase) 

CloseLibrary ( (struct Library *) IntuitionBase) : 



Here we see quite a few changes. First let me mention that it 
is traditional in C to consider the number as representing 
something that is false, and 1 something that is true (K&R, 42). 
Note that the header file <exec/types.h> continues in that same 
tradition by defining the macros TRUE and FALSE as 1 and 
respectively. In the same spirit it is popular to design functions 
within programs to return a 1 if they complete their task success- 
fully, or a if for any reason they fail to do so. Such functions can 
then be called by using the convenient and popular style: 

if ( !My_Function( )) 

1 

/* take corrective action */ 

} 

/* continue normal execution */ 



If the value returned by My_Function( ) is equal to zero 
(meaning that something went wrong) the '!' (K&R, 42) operator 
inverts it, causing the if statement to succeed and execute the 
block within braces to take corrective action. If the value returned 
by My_Function( ) is equal to one (meaning that all went well) the 
if statement fails and normal program execution continues. Tra- 
ditionally you design My_Function( ) to return either a TRUE or 
a FALSE. In the above program example the function Open_Libs( 
) uses that same traditional calling style, exiting the program if 
Open_Libs( ) returns a FALSE. 

Note that it would be incorrect if, in the event that 
"intuition.library" failed to open, the program terminated di- 
rectly from within the Open_Libs( ) function. The Open_Libs( ) 
function may have no idea about the working details of the 
program that called it. That calling program may in fact have 
many details that require attention before it may be safely ter- 
minated. Do you see what 1 mean about making your programs 
usable i n most programming si tua tions? The Open_Libs( ) function 
is simply not in a position to make such decisions. The only thing 
it should do is report to its calling program whether or not it 
succeeded in performing its assigned task. 

Notice also that this same calling style is used within the 
Open_Libs( ) function to call the OpenLibrary( ) function itself. 



I declared the Open_Libs( ) function to be type BOOL, a data 
type borrowed from the PASCAL language which can have only 
two possible values, TRUE or FALSE (1 or 0). BOOL is another 
definition conveniently made for you in <exec/types.h>. Al- 
though in C that declaration doesn't theoretically prevent the 
Open_Lib( ) function from returning integers of value other than 
or 1 , we d esign Open_Lib () so tha t those are the only ones i t can 
return. All this helps streamline the future use of the Open_Libs( 
) function. It's a big help if all your functions follow the same 
conventions. 

In my example I added a separate function for closing the 
library. The if statement verifies whether a the library pointer 
does indeed contain a valid address, rather than a NULL. To 
neglect this test would crash the machine if your program acci- 
dentally tried to close a library that was never opened success- 
fully in the first place. Yes, 1 know that in my simple example this 
is impossible. If the library fails to open, the program terminates 
before it ever gets to the CloseLibrary( ) function. But as you will 
soon see, your programs will be considerably more complex than 
that. They will have to deal with having to close libraries at 
different times in their execution, when perhaps a different 
number of libraries are open. The above idea of testing the pointer 
to a library before closing it will help us design a streamlined 
method for dealing with such complexities. 

MY FINAL VERSION 

So our little test example has now graduated to quite a little 
program. Would you believe we are not actually finished with it? 
Did you notice that I named it Libs, not Lib? My intention is to 
design it so that it opens other libraries as well. You see, I 
recognize that almost all my programming examples will need 
more than one library and therefore I prefer to combine the 
opening of all of them into one convenient, easy-to-use function. 
My approach may be at bit wasteful for those few times when one 
of my program does not actually use every library that it opens, 
but I don't really care about that. This series of articles is for 
instructional purposes, where such conveniences are of greater 
value than scrimping for every last byte of available system 
memory. Besides, these libraries are not very large. Even a 51 2K 
machine can accept this kind of overhead without much com- 
plaint. 

Below I present to you my final Open Libs( ) function that 
will serve us for quite some time. 



#include<intuition/intuitionbase.h> 
#include<proto/exec.h> 
#include<proto/ intuit ion. h> 
Sdefine INTUITION_R£V 33 
#define GRAPHICS_R£V 33 
#define DISKFOMT_REV 33 

struct IntuitionBase *IntuitionBase = NULL; 
struct GfxBase "GfxBase » NULL; 
struct Library *DiskfontBase - NULL; 

BOOL Open_Libs (VOID) ; 
VOID Close Libs (VOID) ,- 
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main I ) 
I 

if <!Open_LIbs(l ) 
exit 111 ; 

printf ("The address of intuition. library is %u\n", IntuitionBase) ; 

printf ("The address of graphics . library is *u\n", Gf xBase) ; 

printf ("The address of diskfont. library is %u\n", DiskfontBase) j 

Close Libs II ; 



spel ling of wha t you are looking for. Tha t problem ha ppens of ten 
when programming the Amiga in C. 

OK, let's suppose you want to know which header file 
contains the version number supported by the compiler. How do 
you find out? Enter into a SHELL window: 

Search SAS_C_5.1 .4 :Compiler_Headers VERSION quick all 



BOOL Open_Libs(VOIDI 



■ 



if I ! UntuitionBase = (struct IntuitionBase *) 

OpenLibraryC'intultion. library", INTUITION REV))) 
( 

printf ("intuition. library could not be loaded. \n") ; 

return IFALSE) ,- 
} 

iflMGfxBase = (struct GfxBase ") 

OpenLibrary ("graphics. library", GRAPHICS REV))) 
i 

printf ("graphics. library could not be loaded. \n") ; 

return (FALSE) ; 



if (! (DiskfontBase = (struct Library *) 

CpenLibraryC'diskfont. library", DISKFONT REV))) 
I 

printf ("diskfont .library could not be loaded. \n") ; 

return (FALSE) ; 



return (TRUE); 



AmigaDOS begins to search all files, reporting their names 
and any line numbers where the string "version" occurs within 
them. Eventually you will see the macro LIBRARYJVERSION 
defined on line 56 of <exec/ types. h> as 34. You can press [CTRL]- 
C to stop the search at any time. Would you like a printout? Enter: 

Search >PRT: SAS_C_5. 1 , 4 :Compiler_Headers VERSION all 

Note that none of this will work if you have installed the 
compiler to a floppy sys tern usi ng the S AS installation procedure, 
but it will work perfectly if you install it using one of the programs 
that come on disk with this magazine. If you haven't already, I 
hope you try one of these installations and prove to yourself that 
your 'Two Floppy Amiga" is really a powerful C language 
development system. 



VOID Close_Llbs<voiD) 
[ 

if ( IntuitionBase) 

CloseLibrary ( (struct Library *) IntuitionBase) ; 

if (GfXBase) 

CloseLibrary ( (struct Library *)GfxBase); 

if (DiskfontBase) 

CloseLibrary (DiskfontBase) ; 



Program Modules, Next Issue 

The above program is all well and good, but you are prob- 
ably wondering exactly how I intend to use it as a module in other 
real projects. Next issue I will present how functions, or groups of 







Hey! What happened to the #include<exec/types.h>? Take 
a look in Compiler_Headers (disk4) at intuition/intuitionbase.h. 
You can use the LSE Editor for this. Enter into a SHELL window: 

LSE SASC_5.1. 4 :Compiler_Headers/ intuition/intuitionbase.h 

At the very beginning of the file are three lines which test if 
<exec/ types. h> has been previously included, and if not to do so. 
Well how about that! The header file system is smart enough to 
know what other files are needed whenever you want to use a 
pa rticularone. So my previous inclusion of <exec/types.h> wasn't 
really necessary after all, <intuition/intuitionbase.h> takes care 
of it for me automatically. I admit now that I included it earlier 
only to draw your attention to its importance. 

AN IMPORTANT AMIGADOS FEATURE 

I would like to close this issue with something that has 
nothing to do with the C language, but which is very important 
when using a development system like SAS. You are now begin- 
ning to realize the importanceof header files, right? Well, suppose 
you need to know what particular header file contains a certain 
definition. Perhaps you do not even know for sure the exact 



I Can't Find the Books? 

The books referenced in this series are necessary tools for the 
serious Amiga programmer. Unfortunately, they may be a little- 
hard to find, and a bit costly. A fantastic mail-order source for 
trade computer books is Communique Professional Books, 
Communique is a mail-order only bookseller that provides great 
service along with great mail-order prices.. .usually 20% off retail. 
Communique also features Free Shipping by US Priority Mail! — 
2-Day Shipping) 

For more information and a complete price list, write to: 

Communique Professional Books 
4263 North Main Street 
Suite 496 
Fall River, MA 02720 

ask for their Trade Computer Titles Catalog & Price List! 
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Advanced ARexx Programming 



Intuition 

and 

Graphics 

in 

ARexx 

Scripts 

byJeffGlatt 



Using the ARexx function library, 
rxjntui. library, which adds a few 
dozen ARexx commands that allow an 
ARexx script to utilize Intuition and 
Graphics library routines. 



Although ARexx has a built-in set of commands that 
cover the basic necessities of looping, math operations, 
file input /output, etc., it has no features that allow it to 
take advantage of the Amiga's tzvo most notable aspects: 
Intuition and Graphics. For example, ARexx doesn't 
have commands for opening windows, attaching menus 
and gadgets, posting requesters, and interacting with 
and waiting for user input. Nor does it have commands 
for drawing lines, boxes, or printing text in various 
colors and styles. It doesn't support the mouse in any 
way. Wltat ARexx does have is the facility to add "func- 
tion libraries" which can add new commands to the 
default, built-in set. I have ivritten an ARexx function 
library, rxjntui. library, which adds a few dozen ARexx 
commands that allow an ARexx script to utilize Intu- 
ition and Graphics library routines. This article demon- 
strates how to use this library to create an ARexx script 
with an Intuition interface. 

The rxjntui.library should be copied to your LIBS: 
drawer, as well as to the dissidents requester.library, 
color.library, ilbm.library, and prtspool.library files. The 
rxjntui. library uses these other libs to implement certain 
features. I've included a program called "InstallLibs" that will 
do all of this copying for you. Make sure that you have about 
36K free room in your LIBS directory. Either click on the 
InstallLibs icon, or from the CLI, cd to the directory with 
InstallLibs and invoke it. Obviously, you also need the ARexx 
product by Bill Hawes (not included here). 

There is a doc file for the rxjntui library called 
"Rexxlntuition." This document describes all of the new ARexx 
commands that are added, their arguments, and what they 
return. Too much information to include in this article, you 
should read that doc file now, and then study the example for 
each command as described in section A. 
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Once you've become familiar with what the rxjntui 
library offers, I wish to show an example of its use. You've 
probably encountered those "Directory Master" programs that 
feature a window full of gadgets that allow you to select disk 
files with the mouse and then copy, delete, rename, etc. The 
program may also allow you to format, copy, re-label, and 
make directories on disks by simply clicking on gadgets. This 
is an example of an Intuition interface. What I intend to do is 
use the rx_intui library to create a window with labeled 
gadgets, get mouse and gadget selections from the user (using 
the FifelO requester to get filename and directory selections), 
and then use ARexx's ADDRESS COMMAND to call the 
appropriate C: command to implement the operation upon the 
user's selections. CLI.rexx is the resulting ARexx script. 

In the first few lines of the script, i open a window, and 
get two FilelO structures for use in obtaining AmigaDOS file 
and disk names. Then, I add 11 BOOLEAN gadgets to the 
window with ID's ranging from to 10. (If you are unfamiliar 
with the difference between boolean, proportional, and string 
gadgets, you could consult the text file called Paint.txt accom- 
panying the article "Implementing ARexx".) These gadgets 
allow me to select one of 11 operations performed on disks or 
directories. The first three gadgets allow me to COPY, DE- 
LETE, or RENAME files (i.e., text files, data files, executables) 
or directories. These gadgets will be labeled with the string 
'FILES' above them. The next four gadgets allow me to create a 
new directory, or copy, format, or re-label (re-name) a disk. 
These gadgets will be labeled 'DISKS'. The next two gadgets 
allow me to read/edit text files by invoking the text editor of 
my choice, or print text files. These are labeled 'TEXT'. The last 
two gadgets allow me to display or print picture files. These 
are labeled 'PICTURES'. 

The IDCMP loop is contained in the DO WHILE class > 
loop. This loop continues until the user clicks on the window's 
close gadget. Inside the loop are tests for whatever actions the 
user makes using the 11 gadgets. The ARexx script is "put to 
sleep" when it calls the WaitMsgC ) function until the user 
clicks one of the 11 gadgets. Upon returning, I parse my 
IDCMP spec into the 4 components of class, parti, part2, and 
part3. For a gadget event, the class will be equal to 1. So 1 know 



that the user clicked one of the 11 gadgets, and next I have to 
determine which one. The parti contains the ID of the selected 
gadget. If the user selected the FILES COPY gadget, then parti 
would be 0. Let's assume this to be the case. 

Now, I have to bring up the file requester in order for the 
user to select which file(s) to copy. By specifying 
MULT1PLE_FILES, the user can select several files in one 
directory. Then, I have to bring up the requester again so that 
he can choose the destination directory. I'm going to copy the 
file to that directory, keeping the same filename. Note that I'm 
using a second FilelO so that I don't disturb the selections 
made using the first FilelO until I'm done with my copying. 
Additionally, I select the SHOW_DISKS flag so that the user is 
presented with a list of volumes. After the user selects the 
destination directory, I zero out the filename field of the 
second FilelO using the Poke function to make sure that only a 
directory path is returned (the destination must be a valid 
directory, not a file). Also note that I check both fname and 
toname for null (") before proceeding. This would be the case 
if the user cancelled, or there was an error with opening the file 
requester. I display a "wait" mouse pointer using the 
RedrawWind function to indicate that this copying is now in 
progress. 

Now, since I enabled MULTIPLEJFILES, I need to extract 
each selected filename from the first FilelO one at a time. The 
functions FirstEntry and NextEntry do this. These functions 
return a null filename when there are no more selections. 
That's why I use the DO WHILE fname > " loop. Using 
GetPath, I obtain the complete source filename and the 
complete destination filename. (FirstEntry and NextEntry only 
return the filename part, minus its root path). Notice how I 
pass fname along with the appropriate FilelO, Finally, I'm 
ready to use ARexx's ADDRESS COMMAND to use the C: 
command "copy." I format the copy template. Note that I add 
double quotes around each complete filename. This is in case it 
contains imbedded spaces. The COPY command (as do most 
C: commands) requires double quotes around arguments with 
imbedded spaces. If not, the quotes won't matter anyway. I 
examine the return value. It should be for success. If not, I 
post an error requester in the window. Next, I append '.info' to 
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the filenames and attempt to copy any icon file associated with 
this copied file. Note that 1 don't check for an error here 
because this icon file might not exist (i.e., if the user was 
copying the serial device). Finally, I get the next selection and 
repeat the process. I drop out when the last selection is copied. 
All of code for the other gadgets is skipped. I drop down to 
where I clear the "wait" mouse pointer. (Even if it was never 
set, this is safe to call.) 

Most of the other gadgets are handled in a similiar 
manner. I use the file requester to obtain the arguments, format 
some template for a C: command, and invoke the command. 
Sometimes, as in the RENAME gadget, I don't allow 
MULTIPLEF1LES, and therefore don't have to extract each 
.selection. For the DISK operations, such as DISKCOPY, I'll 
invoke the SHOW_DISKS flags so that the requester comes up 
with a list of mounted volumes or devices instead of filenames 
in the current directory, ( The user can invoke this list by 
selecting the mouse right button while the requester is open.) 

Occasionally, I'll use the Input( ) command, such as with 
the RENAME gadget, if I only need to obtain one simple 
string. This saves having to bring up the file requester and 
extract one field from it (i.e., just the filename part). 

For the M AKEDIR command, I need to make an icon for 
the newly created directory. Unfortunately, the C: command 
doesn't allow this option, so I achieve this by copying the 
"Empty. info" file from the user's boot disk. If he has deleted 
this file, then no icon will be made for the new drawer. 

A special topic arises with the DISKCOPY command. Note 
that when I format the ADDRESS COMMAND, I'm specifying 
redirected input from the NIL: device ( <NIL: ). Normally, 
when DISKCOPY starts up, a message is posted to the CLI 
background window asking the user to press RETURN to 
initiate the copy. Since I have my own window open and active 
(i.e., all keyboard events go to my ARexx program instead of 
the CLI), the user never sees this prompt and won't respond to 
it. By re-directing input from NIL:, this forces that prompt to 
go away of its own accord, and allows the DISKCOPY to 
proceed without needing to be initiated by the user pressing 
RETURN. 

The FORMAT command presents a special problem. I use 
the file requester to obtain the device name to format. The 
requester does not handle disks that are not formatted, so 
when the user makes his selection, a DOS requester will 
appear if an unformatted disk is in the selected drive at this 
time. Of course, selecting the DOS requester's CANCEL will 
make it go away, and the operation proceeds normally. An 
alternative to using the file requester would be to simply 
"hardwire" some boolean gadgets labeled DFO;, DF1:, etc. for 
the FORMAT command. A new window could be opened with 
these gadgets added to it. Each gadget would have a unique 
ID. The gadgets would be set to ISSUE„CLOSE, so that 
selecting one would close the window as well as return the 



selected ID. A WaitMsg( ) IDCMP on this window would wait 
for and return the user's selection. This is an example of 
"rolling your own" input requester which this library makes 
possible. Here's an example alternative to the FORMAT code: 

t* An example of a custom, input "requester" (actually a pop-up window} */ 
popwind=GetWindow ( 'Select drive to FORMAT' ,,, ,234,40, , 608,4102) 
IF popwind — » *' I popwind »- THEN SAY 'Window open error' 
errmsg - 'Gadg open error' 

I* Add a bool gadg for DFO: with ID - 50. Set it to ISSUE CLOSE */ 
gadg=AddGadg (popwind, 1, 'DFO', 29, 14, 50, 14, 1, 50, 126) 
IF gadg — " I gadg ■- THEN SAY errmsg 

/* Add a bool gadgec for DF1: with ID - 51 */ 
gadg-AddGadg (popwind, 1, 'DF1', 84, 14, 50, 14, 1, 51, 12B) 
IE gadg ■— " I gadg — THEN SAY errmsg 

/* Add a bool gadget for HDD: with ID = 52 */ 
gadg=AddGadg (popwind, 1,'HDO', 139, 14, 50, 14, 1,52, 1281 
IF gadg — " I gadg — THEN SAY errosg 

/* Wait for user event. Parse the 4 parts of spec into separate vars "/ 
classl ■ 1 
DO WHILE classl > 
specl=WaitMsg (popwind) 
PARSE var sped classl myPartl my?art2 myPart3 

/* If a gadget selection, assign the ID to gadgID */ 
IF classl == 1 THEN gadgID - myPartl 
END 
err-EndWindow (popwind) 

/* Now figure out which device string matches the ID 
IF aadalD = 50 THEN tonarae » 'DFO:' 



'/ 



IF gadgID 
IF gadgID 



51 THEN tonaae - 

52 THEN toname - 



The READ gadget invokes a text editor in the C: directory 
called "ed." You can change this by altering the ADDRESS 
COMMAND for that code to the name of your editor of choice. 

Note that the SHOW gadget uses the library's IFFLoad 
routine, allowing the library to open a new window/screen 
combo for the chosen picture. I do a WaitMsgf ) to wait for the 
user to click into that window when he wishes to end the 
display, I must close that window and screen even though the 
library opened them. 

The PRINT picture code uses the Print( ) routine to print 
the picture. This requires that I load the picture into a window 
first. As soon as the Print( ) routine returns — immediately if 
there was enough memory to spool the print job, I can close the 
window/screen. It doesn't matter if the printing is still in 
progress (or yet to begin). For the text PRINT, I use the copy 
command to send the file to prt:, which is the DOS handle for 
the printer device. 

This is one example of what you can do with the rx_intui 
library. There are many other uses. You could write a text 
editor in ARexx, or make a "control" window from which to 
launch a variety of applications. Using the DOS ser: and par: 
devices, you could write ARexx scripts to send information out 
of the serial and parallel ports using string or prop gadgets to 
obtain the data (i.e., a midi patch editor perhaps). Remember 
that you set such parameters as baud rate, data stop bits, etc, 
via preferences. 
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UNIX 

and the Amiga 



An Introduction to UNIX, for the Amiga Programmer— Part I 



By Mike Hubbartt 



The Amiga's operating system (OS) is often criticized — it's 
either too slow, too buggy, or lacks certain "necessary" features. 
Commodore has worked on the reported OS problems and 
deficiencies by releasing updates, from the original VI .0 to the 
much heralded V2.0. But if the Amiga's OS is not MS-DOS nor 
Apple compatible, does it resemble any other OS? The operating 
system most like the Amiga's seems to be the UNIX operating 
system. 

First For UNIX 

There are two classes of UNIX: AT&T's System V and the 
University of California's BSD. UNIX has been around since the 
early 1970's, originally designed as a mainframe OS, although it 
has migrated to 80386/80486 IBM-compatibles. UNIX, now 
adapted by software vendors such as SCO and Interactive to run 
on IBM and compatible microcomputers, can replace the limited 
MS-DOS environment. UNIX is primarily seen at universities, yet 
is migrating to the business sector. 

UNIX is an OS that supports multitaskingand multiple users 
on individual terminals, but requires a much larger hard drive 
and more system memory than AmigaDOS (like OS2 and Win- 
dows 3.0). The complete Interactive 386/ix UNIX, SCO UNIX, 
and SCO Open Desktop packa ges ea ch need atleastallOto 200M 
hard drive (a 600M SCSI is preferable) plus from 4 to 16M of 
system memory (preferably fast 32-bit over slower 1 6-bi t memory ) . 

SCO's Xenix, a subsystem of UNIX for 80286/386/486 sys- 
tems, can operate with a minimum configuration on a system 
with as little as 15Mof hard drive space plus just 2M of memory, 
much less than UNIX. 12 - 15M is enough for the base Xenix OS, 
and just for a single user. The hard drive size plus memory 
requirements for a Xenix and UNIX system are affected by the 
number of people attached by terminals to the system — adding 
people will increase the amount of memory and hard drive 
requirements for a system. 



UNIX allows one or many terminals (and hence other users) 
to connect to a single system, by use of a peripheral called a 
multiport I/O card. The I/O card plugs into an internal expan- 
sion slot in the main PC running UNIX, allowing from one to 64 
terminals to connect by external cables to the main system. A 
sma Her setup wi th the main system using its two serial ports with 
modems to connect terminals is also acceptable. Eachuserhas his 
own log-in name and a private password for entry into the 
system. 

A main UNIX system should be a fast (25MHz or better — 
although 16MHz and 20MHz systems will work adequately on 
smaller setups) 80386- or 80486-class machine, not on an 8086/8 
nora 80286 system. For those with a 80286 system that want to run 
a smaller UNIX network, there are versions of Xenix that will 
handle the job. Xenix will operate on computers with as little as 
2M memory, yet most versions of UNIX require a minimum of 
4M. For those with 8086/8's, sorry. There are a few software 
companies that have UNIX/Xenix lookalikes, and these pro- 
grams will run on 8086/8 systems, even though neither UNIX nor 
Xenix will. If you want a UNIX clone for a 8086/88 machine, try 
MKS Toolkit, Coherent, or Minix. 

Xenix comes in 80286 and 80386 versions, and both versions 
ru n on 80286-, 80386-, and 80486-class machines, with MFM, RLL, 
ESDI, and/or SCSI hard drives. SCSI hard drives are the best for 
use with either UNIX or Xenix, with Adaptec's 1542A and 1542B 
host adaptors as an excellent choice. However, the Adaptec 1522 
host adaptor is not recommended at this time for either UNIX or 
Xenix. There are several vendors of SCSI host adaptors that work 
fine with UNIX. Check with the UNIX or hardware manufacturer 
before buying if you have doubts. 

One or more UNIX/Xenix applications (a.k.a. programs) can 
run at the same time on a system used by one or many users. 
Applications can be large databases, where several people use 
different terminals to access a common pool of information. 
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Installing UNIX is a lengthy procedure — several hours at 
least for just the operating system. Both SCO and Interactive 
UNIX come on anywhere from 25 to 80 high density diskettes 
(either 5.25" or 3.5"), and it takesquitea while just to swapall those 
disks after the information has been read into the system. The 
number of applications (for example, network support, TCP/IP, 
and C Programming) chosen affect how many disks are needed, 
since the disks are organized by application. Both SCO and 
Interactive check the hard drive forerrors before laying down the 
OS. The hard drive is used for temporary storage of data from 
system memory, when the system has a greater demand on 
memory than available from system resources. The hard drive 
needs to be as error-free as possible to avoid corrupting applica- 
tion data or the OS itself when the data is written to and read from 
the hard drive Into memory. 

With SCO's UNIX and Xenix, you can have an MS-DOS 
partition on the same hard drive as UNIX or Xenix. This is useful 
when you consider how many DOS business applications are in 
use today, and how many UNIX users may not want to give up 
their favorite DOS program. The procedure for a dual OS drive is 
simple: 

1 ) Use DOS's fdisk to remove all DOS partitions on the 
hard drive; 

2) Use DOS's fdisk to set the DOS partition first, use the 
DOS "format /s" to high level format the DOS partition, 
and then install DOS on the partition; 

3) Boot the system from the UNIX/Xenix Boot disk; 

4) Create a UNIX/Xenix partition, starting immediately 
after the end of the DOS partition; 

5) Make the UNIX/Xenix partition active (not the DOS 
partition), and then complete the SCO installation. 

When the system is turned on, SCO Boot: is on the screen. 
Pressing the<Enter> key will boot the system up in UNIX/Xenix, 
while typing "DOS" and pressing <Enter> will bring the system 
up in the MS- DOS environment. Your default boot string isstored 
in the /etc/default/boot file — it is 'DEFBOOTSTR='. 

Now For The Amiga 

So how does UNIX apply to the Amiga? Commodore is 
working on releasing a version of UNIX for the Amiga, which 
shows their support for this useful OS. Prentice-Hall has pro- 
duced Minex For The Amiga, a mini-UNIX which works on 
Amiga 500/2000/2500/3000's. Additionally, there have been 
several UNIX shells for the Amiga — Jay Ts' T-She!l and a few 
shareware/ PD shells found in the Fred Fish library. 

Both the Amiga and UNIX can use either a command line 
environment (the shell) to enter commands, or they both can use 
a graphic interface. The Amiga and UNIX graphic interface 



supports use of a mouse to select applications, saving the key- 
strokes needed to start the application and all the specified 
options. The normal Amiga Mouse has two buttons, while three- 
button mice are recommended for the X*Windows graphic envi- 
ronment. The graphic interface of UNIX is easier to use than 
typing in commands, since it uses icons just like the Amiga's 
Workbench. Both UNIX and the Amiga allow access to the 
command line from within the graphic interfaces — the Amiga 
has its Shell (just like SCO's Open Desktop) icon available when 
opening a main Workbench window (at least that's how I set up 
my hard drive's Workbench). 

Both the Amiga and UNIX have several different shells, 
although UNIX has several different graphic environments — 
X J Windows, Open Motif, Looking Glass, and Open Desktop. 
Open Desktop is SCO's product that incorporates their SCO 
UNIX System V 3.2 Rev 2, into a graphic interface, and is available 
for around $1000. Looking Glass and Open Motif are extra 
interface programs that cost around $500 each, in addition to the 
cost of the UNIX package itself (priced from $600 - $1500 and up, 
depending on the applications needed). 

Piping, the output of one command into another, is sup- 
ported on the Amiga and in UNIX environments. An example of 
piping is: #dir dh0:c I more. This line directs the output of the 
directory of the c directory, into the MORE utility. Since More 
allows displaying a large file one screen at a time, you have time 
to see all the files in the C directory if there are more than your 
screen will hold at one time. Since the screen normally scrolls 
unless a key is pressed when listing a long directory, this particu- 
lar example takes the guesswork out of knowing when to stop the 
scrolling. 

Re-direction, an Amiga and UNIX feature, utilized (with the 
">" and "<" characters) between commands on the same com- 
mand line also saves a lot of typing time. Here's an example of 
Amiga re-direction: 

# dir > prt: 

This line re-directs a listing of the current directory out to the 
printer This is useful when you have a lot of files on a disk and 
want a list handy for reference. This method saves time, since 
systems that fail to support re-direction require an intermediate 
step to accomplish the same purpose. UNIX does use Ip filename 
to send output to a printer, although re-direction is supported as 
shown by the next example: 

Is -1 > special_file 

This line redirects the output of listing the current directory from 
the screen to a file called special_file. 
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AmigaDOS and UNIX Commands 
Copy and CP 

Many UNIX commands are similar to Amiga commands. 
They use CP to copy files from one directory to another for UNIX, 
while Amiga CLE has the COPY command. COPY dfO:cando/ 
text/testfile dhO.-cando/text is same as CP /usr/text/testfile / 
usr/newdir. 

The AmigaDOS Copy command has the following options: 
All, Quiet, Buffer, Clone, Date, Com, and Nopro. The UNIX CP 
command lacks these options, since re-direction of input and 
output is such an integral part of the OS. 

CD and Date 

CD and DATE are used by both AmigaDOS and UNIX to 
change/display the current directory, and to provide date infor- 
mation. Both the AmigaDOS and UNIX CD lack any optional 
fl ags . The Amiga DOS Date shows or sets the sys tern time and has 
Date, Time, and To options. 

The UNIX Date command is loaded with output display 
options. +%a uses the 3-letter abbreviation for day of the week; 
+%D has the date displayed in mm/dd/yy format; +%d day is 
shown as 1-31; +%H time is in 24 hr clock (0-2300); +%h uses the 
3-letter abbreviation for month; +%j shows Julian date, from 001 
to 366; +%M shows minutes as 00 - 59; +%m shows month as 1 - 
1 2; +%n inserts a newline, to add a space between the date and the 
next command line prompt; +%r adds AM or PM time designa- 
tors; +%S shows seconds as - 59; +%T shows the time as 
hh:mm:ss,such as 10:42:16; +%tacts to insert a tab, to separate the 
information; +%w shows the day of the week as a number instead 
of with letters — it shows a instead of SUN for Sunday; +%y 
shows the year as 00 - 99. 

These options can be chained together for more detailed 
information. For example, Date "+%D %a" which displays 02/ 
1 /91 Su n, f or February 1 0, 1 991 . If the options were no t enclosed 
within "", only the date 02/10/91 would be displayed. Another 
example would be, Date %D%t%T which displays 02/10/91 
14:08:06, for the same information in the previous example, plus 
the time tabbed away from the date. Note that this example did 
not require the use of "" to encase the options. 

Dir, LS, and LC 

The Amiga DIR command gives a listing of the specified 
directory, while UN IX provides LS (short for LiSt — an AmigaDOS 
command) and LC (short for List Column). With AmigaDOS, you 
might use DI R d hOx or LIST dhOx for a listing of all files in d h0:c. 
DIR (in AmigaDOS 1.3) only has a few option switches — A, 
,AI„and D. 



LS has many useful options: -a lists all entries, including files 
starting with "." — such as .profile; -b shows all non-printing 
characters in octal; -C displays the specified directory, in Colum- 
nar form; -c utilizes the "time" field for last modification time; - 
d lists directory names, but not files; -F has / to show directories 
& * to show executable files; -f lets you specify several directories 
a t once; -g prints a long list (-1), but without the file owner; -i prints 
the inode number; -1 for Long LiSt, which shows the file sizes, 
group, links, owner, mode, and when the files were last modified; 
-m prints out the files across the screen, separating each file with 
commas; -n prints the long list (-1), but utilize group/numeric id; 
-o prints the long list (-1), but excludes the file group; -p uses an "/ 
" to indicate the directories; -q prints a "?" to display any non- 
printing characters; -R shows all files in the directory, as well as 
the files in subdirectories, -r displays the directory, sorted in 
reverse order; -s lists the files with their size in blocks; -t lists files 
sorted by the last time accessed, although the times themselves 
are not displayed; -u displays files based on the time of last access; 
-x displays the file across the screen in columnar form. 

LC has the same flags as LS, except for the following differ- 
ences. -A is the same as -a, except it does not show "." files; -1 
forces the display to single items for each line (just like the plain 
LS command). 

ECHO 

Echo isfound in both AmigaDOS and UNIX. The AmigaDOS 
command has three options: Noline, First, and Len. The UNIX 
version has considerably more options. \b is a backspace; \c 
causes a line to print without a newline; \f causes a form feed; \n 
causes a newline; \ # sends an octal value out; \r causes a carriage 
return; \t gives a tab; \\ gives a backslash in the output text. 

MORE 

More is a utility in AmigaDOS that allows someone to 
display a tex t file on the screen withou t usi ng a text editor or word 
processor. Environmental variables are supported on the Amiga 
and in UNIX. If More is started from either the shell or CLI, setting 
the Amiga EDITOR environmental variable allows bringing up a 
chosen text editor while within More. Both the AmigaDOS and 
UNIX versions of More accept input via piping. 

The UNIX version of this command has quite a few options. 
The + /pattern displays the text two lines before the start of the 
pattern specified; -c clears old then redraws screen for each page 
of text; -d get a prompt at the end of each screen; -f count lines 
within the file, using newlines instead of basing the count by 
number of screen lines (as is normal); -1 ignore any formfeeds; -n 
for window size; +n set the line to start viewing, within the 
specified file; -r show control characters on the screen; -s elimi- 
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Recently, we were ordered by 
U.S. military officials to explain to 
their complete satisfaction just 
what a SuperSub is (as we all 
know, it's the best subscription 
deal around for Amiga users, 
since it includes both Amazing 
Computing MidAC's GUIDE). 
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1 hen, a prominent Congressman 
wired to ask us if we would testify 
before a top-secret subcommittee 
as to whether or not we can pro- 
duce a single prototype SuperSub 
for less than $500 million (is this 
guy kidding? - a one-year 
SuperSub costs just $36 - and we 
can produce one for anybody i). 

rinally, a gentleman called us 
from Kennebunkport and told us 
to read his lips, but we told him 
we couldn't, because we don't 
have a picturephone. 

And then he ordered a SuperSub. 



AC'S SuperSub - 
It's Right For You! 

call 1-800-345-3360 



List Of 
Advertisers 

Please use a Reader service card to 
contact those advertisers who have 
sparked your interest. Advertisers want 
to hear from you. This is the best way 
they have of determining the Amiga 
community's Interests and needs. Take 
a moment now to contact the compa- 
nies with products you want to lean 
more about. And, if you decide to 
contact a advertiser directly, please tell 
them you saw them in 

AC TECH^miga 
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nate multiple blank lines, displaying only 1; -u stop underlining 
or character enhancement; -w give a terminate prompt at the end 
of the file. 

Amiga and UNIX Editors 

Ed, an archaic/weak/boring screen editor, is found for the 
Amiga and UN IX. Bo th AmigaDOS and UNI X also ha ve the EDIT 
line editor commands, and both support piping — which con- 
nects the output of one process or command into another. An- 
other surprise — Memacs is available on both Amiga and UNIX 
platforms. 

The most powerful UNIX editor is Vi, pronounced "Vi", 
"Vee-Eye", or "Six" by people in the UNIX crowd. Although 
having used it for years, I still feel Vi is probably the least intuitive 
editor I've ever used. I use Vi regularly when C programming in 
a UNIX environment but would note that it takes a while (or a 
good help chart on-hand) to learn it well. This editor comes with 
SCO Xenix & UNIX, and with Interactive UNIX. There are several 
good pd/shareware versions of Vi for the Amiga in the Fred Fish 
Library (such as Stevie) for the curious. The Manx C compiler 
comes with Vi, for those diehard UNIX people that are so used to 
it and prefer it over Amiga text editors with pull-down menus like 
TxEd+ and CED. Although not provided with standard Amigas, 
Vi does come with the Amiga 3000UX. 

Fred Fish Amiga UNIX Goodies 

For Amiga owners wanting to use UNIX commands or 
utilities on their systems without going to a UNIX OS, there is a 
way. If you haven't discovered yet, the Fred Fish Library is loaded 
with goodies for programmers, utility addicts, and UNIXheads. 
It would take too much space to cover most of the authors that 
have contributed time and energy to produce UNIX commands 
and utilities for the Amiga community, but we will mention a few 
and some of the UNIX items they wrote or ported. Not all the 
versions of a program or utility by the same or different authors 
will be mentioned. 

For communication setups, William Loftus and Matt Dillon 
have ported UUCP to the Amiga . UUCP stands for UNI X to UNIX 
Communication Protocol. William's port is on FF 152 and in- 
cludes the cron, mail, and compress UNIX commands and utili- 
ties; Matt's version of UUCP appears on FF360. Matt Dillon also 
wrote DNET, a program that allows linking an Amiga to another 
system running BSD4.3 UNIX. This program appears on FF 294. 

As for UNIX commands and utilities, there are many. 
UNSHAR, by Eddy Carroll, appears on FF 345, while Gary 
Glendo wn's MAN is on FF 241 . Justin McCormick brought us LS 
on FF 236, while George Musser and Paul Kienitz produced a 
version of WHO that tells what tasks are currently running on the 
system. Edwin Hoogerbeets wrote MV, a program from FF 219 



that does the same as UNIX's MV, CP, and RM commands — it 
will move files, copy files, or remove files. G.R. Walter released 
STEVIE (on FF217), a port of the UNIX VI editor — not a popular 
one since it is not as intuitive as many would prefer. GNUGREP 
is Henry Spencer's program that does the same as the UNIX 
commands grep,egrep, fgrep, and bmgrep. It is on FF295. Tomas 
Rokicki' s SPELL, on FF 1 91 , is a port of the UNIX spell checker and 
very useful for those using a PD /shareware text editor to write 
letters. One last author I'll mention for now is Gary Brant, who 
released UNIXUTILSon FF179. UNIXutils have WC, Head, Tail, 
Tee, Detab, Entab, and Trunc, and I can attest to the usefullness of 
the WC word counter program for writers. 

Amiga UNIX Shells 

For the Amiga, there are a couple of choices for UNIX shells. 
Matt Dillon has Csh, his Csh-like shell for the Amiga out for 
several years, which he continues to upgrade for us, I started out 
with Ma tt's Csh, since I had only a 51 2k sys tern with a single drive 
and wanted to do more that swap disks whenever I wanted to run 
a program from a disk other that the Workbench disk. Csh has 
built-in commands that are available for use even if the disk is out 
of the drive, so it is a lifesaver for single drive systems with little 
memory to waste. The HELP key on the Amiga keyboard brings 
up a listof the built-in commands forCsh. I'm glad to see someone 
actually using this key. Csh still gets plenty of use, even though 
my setup has grown considerably since first purchasing an 
Amiga. Csh appears on Fred Fish disk 331. 

Although it is newer to the Amiga, I'm impressed with Steve 
Koran's SKsh —.a UNIX Korn shell lookalike. Setting up SKsh 
takes a bit of time — if you try running it without reading the 
information, you'll definitely visit the guru (unless you always 
run a 10k stack)! I made a boot disk for SKsh, and also installed it 
on my hard drive (along with Bill Hawes' Wshell). 

SKsh offers several enhancements over the AmigaDOS 1 .3 
shell. Command substitution, definable shell functions, local 
variables and local aliases, and EMACS-style line editing are a 
few of the new features. I/O re-direction, pipes, and ARexx are 
supported in SKsh. More than one command can be run from the 
command line by using a semi-colon to separate them. SKsh has 
both built-in and external commands, and the external com- 
mands can be resident. The UNIX wildcards are supports, so feel 
free to use *, ?, and [] in place of known characters. There is 
sufficient documentation provided with SKsh, including infor- 
mation on known bugs, built-in and external commands, how to 
install the shell, and reference information on examples for 
writing scripts in SKsh. 

SKsh needs AmigaDOS 1.3, plus a stack of 10,000 minimum 
to function. Both .skshinit and .skshrc must be in the S: directory, 
and arp.library must be in the LIBS: directory. Something to note: 
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this program has reported errors when running with older ver- 
sions of arp. 1 ibrary (no da tes were given), so use the most current 
version available. Theexternal commands, located either in the C: 
or a user i selected directory, are cat, cmp, cp, crc, cut,du, encr, 
fgrep, grep, head, indent, join, num, srun, strings, tail, tee, view, 
wc, window, and xd. SKsh is available on Fred Fish disk 342 and 
is freely re-distributable, but it is not in the public domain since 
it is copyrighted by Mr. Koran. While Steve does not ask for 
shareware status, this product is certainly worth a donation so 
that Steve will continue to upgrade it. 

Commercial Amiga UNIX Products 

There are currently just a few commercial Amiga Unix 
products. Jay Ts' T-Shell has been out for several years, although 
it hasn't been updated for quite a while. The Tshell and all its 
applications eat up space. I load the help info into RAM, speeding 
up the display of info from this shell. Loading the help files and 
some of the applications on a hard drive also speeds up things. 
When I copied the help files from the floppy into memory, it took 
4 min., 1 7 seconds for the T-Shell to be up a nd running. When I ran 
B.A.D. on the copy of the T-Shell disk (never on an original), the 
loading time dropped to 2 min., 5 seconds, clearly showing the 
worth of optimizers. T-sheli uses UNIX-like commands, and 
allows the user to also use Amiga commands so learning the shell 
is painless. 

Prentice-Hall's Minex For The Amiga is a new product. 
Although not advertised, this program deserves some attention. 
Minex was previously available only for IBM 8086/8 and 80286- 
class machines. The Amiga version is $16 third party vendor 
(Unipress) that has C source code only for the IBM version that is 
just $99. Let's hope they bring it over to the Amiga Minex! 

Summary 

Very few people have claimed UNIX is easy to learn, Yet this 
powerful OS has many features found in the Amiga, even though 
the system hard drive and memory requirements are much 
grea ter than what the Amiga needs to do the same task. UNIX can 
be a convenient platform for the Amiga, allowing Amigas to run 
on networks with other PC's, thereby helping to persuade busi- 
nesses to go with the Amiga. We already know that the Amiga is 
an ideal and inexpensive platform for multimedia and animation. 

Passing information and files between the Amiga and other 
platforms easily could spur on sales needed to keep the Amiga a 
major player in the market for a long time. Seeing how Commo- 
dore is pushing the 3000UX at UNIX expos around the world, 
they (and the IBM/UNIX community magazines seem to agree) 
obviously feel so. The Amiga 3000UX was shown at UNIX Galli- 
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tions at Anaheim, CA, at UNIX Expo in New York, at Comdex in 
Las Vegas, and at Educom in Atlanta, GA. The 3000UX comes 
configured a an Amiga 3000 with either a 4M/100M (4M memory 
and 100M hard drive space) or 8M/200M system. CBM recently 
started publishing Amiga UNIXTech Notes to keep Amiga UNIX 
users current on tips and new ideas. 

Should UNIX receive more support from Amiga owners or 
developers at this time? I think anything that would help expand 
the sale of Amigas, without hurting the Amiga's image as a 
serious computer, deserves consideration. There are many UNIX 
tools to examine in the Public Domain but not enough in the 
commercial marketplace. The Amiga 3000UX, Minex, and Tshell 
are useful, but I hope we'll see even more UNIX support from 
many Amiga developers in the near future. The next time you 
pick up a Fred Fish disk, try out some of the UNIX commands (if 
any are there) and see ho w similar they feel when compared to the 
Amiga's commands. You may then feel like trying out a better 
shell than the WorkBench 1.3 Shell —one like Steve Kern's SKsh 
or Matt Dillon's Shell. In the next severat UNIX articles here in 
AC's TECH, we'll look at setting up both the SKsh AND Dillon's 
Shell, starting with a WorkBench disk and cutting it down to the 
bare essentials. 
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A Meg and a Half on a Budget 

Add 512K RAM to your 1MB A500 for about $30 



by Bob Blick 



Project Description 

Here is an inexpensive and easy project for the do-it- 
yourselfer to boost his Amiga 500 from 1 megabyte of RAM to 
1.5 megabytes. Unlike most after-market memory upgrades, 
this doesn't require you to discard your A501 memory board. 
With this project you add extra RAM chips to your existing 
memory board by piggybacking the new chips on top of the 
old ones, and adding a small circuit board containing the 
necessary logic to enable the new RAM. The memory auto- 
configures and no special startup sequences are needed. Total 
investment: one evening and about $30. 

No special tools or parts are required for this project. The 
RAM control circuit can be hand-wired on perfboard, or a 
printed circuit board can be made using the layout at the end 
of this article. An etched and drilled circuit board is also 
available. Anyone who has electronic circuit or kit-building 
experience should be able to complete this project in a few 
hours. However, this is not something for the faint at heart — 
you must take your Amiga completely apart and put it back 
together again, and you'll have to do some soldering. Beware! 
All warranties on your Amiga will be voided, and you alone 
will bear responsibility for failure or enjoy the fruits of success. 
Many of these upgrades have been supervised by the author, 
but nothing's guaranteed — you must double-check every- 
thing and be prepared to undo what you did if you can't get it 
to work. 

System Requirements 

The Amiga 500 comes stock with 512k RAM. If you're like 
most Amiga 500 owners, you bought a Commodore- Amiga 
A501 memory cartridge. It gives you an extra 512k of RAM for 
a total of 1 megabyte and has a clock/calendar chip in it. It's 
housed in a triangular metal box that plugs into the bottom of 
the Amiga behind a plastic cover. You should check, however, 
because there are many A501 clones by other manufacturers. 
The only real difference is usually the omission of the metal 
covers on the clones. The upgrade will work with almost all 
boards, but my directions are specific for the A501, so you 
might need to figure out some things for yourself if you don't 
have the A501 . 



There are a few different versions of the A500 
motherboard. I've seen only one version in all the computers I 
have looked into. You'll have to remove the covers to deter- 
mine your version. Mine has "A500 REV 5" etched into the 
motherboard between the disk drive and the A501 expansion 
connector. This upgrade will work on any Amiga 500 that has 
512k on the motherboard and an A501-type memory expan- 
sion. If your motherboard is not a REV 5, there may be some 
differences. 

The power requirements for this expansion are minimal, 
so the power supply of the Amiga will not be over-taxed. 

The Amiga 500 has a DMA controller chip known as "Fat 
Agnus." The number for it is 8370 or 8371. If you have up- 
graded to the 8372 "Super Fat Agnus," also known as "1 Meg 
Agnus," this project will not work for you. Check in a future 
issue for a 2-megabyte project for "Super Fat Agnus" owners. 
If you don't know which Agnus is in your Amiga, boot with a 
Workbench disk, open a Shell window, and type in "avail" 
<return>. Leave out the quote marks. You will be shown how 
much "chip" and how much "fast" memory you have. You 
should have approximately 512k each. After this RAM 
expansion, you will have 1 meg of fast and 512k of chip. 

Getting Started 

Before getting the parts, you should familiarize yourself 
with your Amiga by taking it apart. Take out the A501 
memory board from the bottom of the computer first. Pry off 
the plastic door and slide the A501 out. If it's a real A501, it is 
encased in a triangular metal box. The box has four metal tabs 
bent over and soldered. Pry them back with a soldering iron 
and open the box. A battery is on the board, so don't set the 
bare board on a metal surface or otherwise you will short 
circuit the battery. You should see sixteen chips with sixteen 
pins each (256-kilobit RAM chips) and one chip with eighteen 
pins (clock/calendar chip). Other memory boards with sixteen 
RAM chips are compatible with this project. If you have only 
four RAM chips with twenty pins each, you have 1 -megabit 
chips. This will require changes in the parts needed and in the 
modification of the memory board. 
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"With this project you add extra RAM chips to your 
existing memory board by piggybacking the new chips on 
top of the old ones, and adding a small circuit board 
containing the necessary logic to enable the new RAM. 
The memory auto-configures and no special startup 
sequences are needed. Total investment: one evening and 
about $30." 




There are six T10 Torx screws holding the case of the 
Amiga together. If you don't have a Torx driver, use a 2 
millimeter or 5/64 inch alien wrench. A small screwdriver 
might also work. The top of the Amiga will snap open easily, 
exposing the keyboard and shielded metal cover. Disconnect 
the keyboard by unplugging the ground wire by the disk drive 
and the multipin connector inside the metal shield. Make a 
note of the way it plugs in, with the black wire on the left. 
Bend back the metal tabs, remove the four Torx screws, and 
the metal shield. You'll see the motherboard, so now is a good 
time to check whether you have a REV 5 motherboard (printed 
on the right side of the motherboard near the disk drive). If 
you have a different motherboard, the directions for the 
modification of the motherboard may not be right and you'll 
need to use the schematic as a reference. 

Double-check the Fat Agnus chip. It 's the big square one 
and may have a metal clip holding it in. It should have 8370 or 
8371 printed on it, as well as other numbers. 

If you are satisfied with everything, check the parts list, 
get the parts you need, and get to work! 

So Build the Thing, Already! 

There are three steps to expanding your RAM: building 
the RAM control board, adding RAM chips piggyback-style to 
your A501 board, and connecting the RAM control board to 
the Amiga's motherboard. Let's start with the RAM control 
board. 

The RAM control has five simple chips on it and sends 
signals to the RAM chips. You can hand wire the circuit on 
perf board, but it's easy to make mistakes that way. A printed 
circuit board is fairly foolproof. The easiest way to obtain the 
board is to purchase an etched and drilled PC board from the 
author. If you like to etch printed circuit boards yourself, I 
recommend using TEC-200 film to transfer the image to 
copper-clad circuit board. With this process you photocopy the 
PC board layout onto TEC-200 film and then use a regular 
dressmaker's iron to transfer the black photocopier toner onto 
the copper-clad board. It's now ready to etch using ferric 
chloride etchant. Check the parts list for a source of TEC-200 
film. Directions are included with each package. 



Follow the parts placement diagram for stuffing the PC 
board. I recommend using sockets for the chips. Pin one for 
each chip is indicated on the board with a rectangular pad. 
Line the notches on the sockets up in the direction of pin one. 
Solder the sockets to the board. The five 0.1 microfarad 
capacitors are indicated by ovals in the diagram. Solder them 
and clip the leads close to the board. The wire you cut off can 
be used for the six short jumper wires. Solder them in and clip 
the excess close to the board. Use ribbon cable for the wires 
that will connect the board to the Amiga. Prepare the ends by 
stripping and tinning with solder. You need a piece with six 
wires, one with five wires, one with two wires, and one single 
piece, all six or eight inches long. Attach them to the RAM 
control board as shown. Press the chips into their sockets, 
aligning pin one with the notches. This completes the RAM 
control board. 

Modifying the A501 board involves a lot of soldering — 
over 240 connections. It's repetitious and boring work and 
hard to do every solder joint right the first time. But after a 
little practice it gets pretty easy. You must piggyback the 16 
RAM chips on the board with another RAM chip and solder 
the pins where they touch each other. Test fit the chips to see 
whether they fit snugly over the chips on the A501 board. If 
every pin touches, it makes soldering easier. If you need to, use 
the flat surface of a tabletop to bend in the pins a little. Next 
you must bend out pin four on all the chips. All of the pins of 
the piggyback chips, except for pin four, get soldered to the 
bottom layer. Pin four is *RAS, or Row Address Strobe, and it 
needs to be connected to the RAM control board. Note: *RAS is 
also pin four on 1-meg chips with 20 pins. 

Take a pair of needlenose pliers and bend the lower part 
of pin four out to the side on all 16 of the new RAM chips. 
Don't bend the pin right near the body of the chip, as it may 
break off. Bend it at the thinner part of the pin. Solder the chips 
one at a time to the A501 board, starting at the end away from 
the connector of the A501 board. Use thin solder and a 
soldering iron with a miniature tip. Getting a good solder 
connection involves heating both pins. It's hard to get to the 
lower layer without solder bridging to nearby pins. Let the 
chip cool off after every few pins if it gets really hot. 
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After soldering all the chips, connect pin four of all the 
piggyback chips together. Wire-wrap wire or other small 
gauge solid wire is useful for this step. With wire-wrap wire it 
is possible to use just two or three pieces of wire to connect all 
the chips, daisy-chain style, and still have insulation on the 
wire between each chip. The insulation on this type of wire 
will slide along easily, so you can strip inch-long sections of 
insulation on one long piece of wire. Connect the two rows of 
eight chips together as shown, along with a 33-ohm resistor to 
the last chip. The other end of the resistor gets soldered to a 
previously unused terminal on the connector. In the Amiga 
schematics it is numbered pin 37 and is the tenth pin from the 
back end of the connector, on the top row. Double-check your 
work, but don't put the metal covers back on the board at this 
time. 

The RAM control board must intercept signals between 
chips in the Amiga. A total of four circuit board traces must be 
cut on the motherboard. Three cuts are on the bottom, so the 
motherboard must be removed. After disassembling the 
Amiga as described earlier, continue by removing the three 
disk drive screws on the bottom and one inside the Amiga. 
Disconnect the two disk drive cables from the motherboard, 
noting the direction they are connected (red towards the disk 
drive). Remove the two hex-headed screws on the RGB video 
connector. Pull the motherboard out of the case and take the 
metal shield and cardboard insulator off the bottom of the 
board. 

Before cutting any traces on the board, look at the inset 
box on the parts placement diagram. One of the wires from the 
RAM control board needs to connect to pin 56 of the Agnus 
chip via a soldered hole in the motherboard. As indicated in 
the diagram, it is near RAM chip U26 towards the front of the 
motherboard. If you are unsure, you may want to use an 



ohmmeter to double-check. This soldered hole is also con- 
nected to pin 35 on the Gary chip. Use the ohmmeter to check 
the connection from this hole to Gary pin 35. 

Locate the Gary chip by the markings on the board. It has 
48 pins. The pins are numbered from the top, counterclockwise 
starting at the notched end. Pin 35 is on the side towards the 
front of the computer. If it checks out, find pin 35 on the 
bottom of the board. The thin copper trace leading to the pin 
must be cut. Use a sharp knife or razor blade and cut the trace. 
You need remove only enough copper to break the connection. 
Locate the chip U35. It is near the front of the computer close to 
the motherboard's RAM chips. It is marked 74F244 and has 20 
pins. Do not confuse it with U34, another 74F244 close by. On 
the bottom of the board, cut the traces leading to pins 2 and 4 
ofU35. 

Turn the motherboard right side up and plug the A501 
board into it. Note the pin that connects to the resistor you 
added to the A501 board. You may remove the board now. On 
the motherboard you must cut the trace to that pin. It is the 
tenth pin from the back of the computer. This completes the 
cutting. Except for the wire to the soldered hole, the connec- 
tions from the RAM control board to the motherboard are 
soldered to chips on the motherboard. Before soldering on the 
wires, tie the pins close to the body of the chips with some 
solder. 

The wires from the RAM control board are long; you may 
wish to cut them shorter for neatness. The board is meant to be 
located in front of Agnus and held in place with double-sided 
foam mounting tape. Five wires connect to U35, two wires to 
Gary, one connects to the soldered hole. The other group of six 
wires connects to the 68000. This is the largest chip, at the left 
edge of the motherboard. It has 64 pins. Five of the wires 
connect on the far left side. The wires are in reverse order and 
the ribbon cable will do a flip. Note that pin 49 should not be 
connected to anything. After all the connections are made, 
double-check your work for solder globs and stray bits of wire. 
Your Amiga is ready to test. 

Checkout and Reassembly 

Before re-assembling the computer, you would be wise to 
check that everything works as planned. Set the motherboard 
on a non-metal table and attach the two disk drive cables and 
one or two screws to keep the disk drive from flopping 
around. Hookup the monitor, mouse, and power supply. 
Don't plug the A501 board or keyboard in yet. Tum on the 
computer and boot a Workbench disk. The computer should 
boot and show 400000 or so of RAM. If the computer doesn't 
work, chances are good you have connected one or more RAM 
control board wires to the wrong place or have a short circuit, 
solder bridge, or cut more than four traces. It should be easy to 
find the problem. 

If the computer works, turn it off and plug the A501 board 
in. It is possible to offset it by one pin, so pay attention. Turn 
the computer on and Workbench should boot and show about 
1400000 free memory. Make sure windows, icons, and menus 
work properly, and turn the computer off and try again just to 
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make sure. If the computer doesn't work, check your A501 
board carefully for solder bridges. If the computer works but is 
flaky or shows less than the right amount of memory, check 
the A501 board for pins that aren't really soldered. Check the 
RAM control board to make sure the chips are in the correct 
sockets. You also might have forgotten to put the chips in! 
This completes the testing. You may re-assemble the 
computer. The metal cover for the A501 board will need a few 
taps with a hammer before re-assembly in order to fit over the 
piggybacked chips. You could leave the cover off, but the 
computer will produce more radio interference without it. 
Make sure the insulating sheet goes on with the bottom cover. 
Before shutting the case on the computer, make sure the disk 
drive is connected properly and check that the plastic sheet is 
in place on the back of the keyboard, and remember to re-plug 
the keyboard. After assembling the computer, test it again 
before putting your whole system back together again. 

How It Works 

The circuit on the RAM control board has two main 
features. One part tricks the Gary chip and the other part tricks 
the Agnus chip. One of the functions of the Gary chip is 
decoding RAM addresses. The 74F20 detects when RAM is 
being addressed in the 512k block just above the normal 
expansion block of RAM. When this happens, the Gary chip is 
fooled into thinking that normal expansion RAM is being 
addressed. The 74F74 flip flop detects which bank of RAM is 
being addressed and locks the other bank out. 

Kickstart 1.2 and 1.3 automatically check for RAM at these 
addresses, so this RAM is auto-configuring as FAST RAM. Any 
memory that connects to the A501 connector shares the same 
bus as CHIP RAM. However, the Amiga only distinguishes 
between CHIP RAM and FAST RAM. This type of memory is 
sometimes called SLOW RAM. The only real way to have 
FAST RAM is to connect to the processor bus. That is the 
connector at the far left edge of 
the Amiga, hidden by a small 
plastic cover. Memory connected 
there is really FAST RAM and 
can speed the Amiga up by as 
much as 35%. The additional 
required circuitry is significant, 
so most manufacturers make 
memory expansions that plug 
into the A501 connector. 



$j^ Memory 
Management, Inc. 

Amiga Service 
Specialists 

Over four years experience! 

Commodore authorized full service 

center. Low flat rate plus parts. 

Complete in-shop inventory. 

Memory Management, Inc. 

396 Washington Street 

Wellesley, MA 02181 

(617) 237 6846. 



Circle 1S6 on Header Service card. 



During RAM refresh all RAM (chip, expansion, and 
piggyback) must be enabled. The rest of the circuit takes care 
of this. When Agnus asserts pins 20, 56, and 57, both expansion 
and piggyback RAM are enabled. There is an unused section of 
the 74F244, U35 on the motherboard. It is used to buffer the 
CAS signal to the piggyback RAM. 

Substituting Parts 

Dynamic RAM chips are made by many companies and 
have many different part numbers for equivalent parts. The 
ones you want are 256k by 1 bit. The access time should be 150 
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PARTS PLACEMENT 
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nanoseconds or less. Faster will not make your system run 
faster, just cost more. These chips are typically called 41256-15, 
and any company that sells RAM for IBM-type machines will 
be quite familiar with them. The prices are quite competitive, 
so shop around. If you have a memory board with four 20-pin 
RAM chips, you need four 1-meg (256k by 4 bits each) RAM 
chips of the 514256 style. 

In order to prevent timing errors caused by signal delay in 
the added logic, 74F (as in Fast) series chips are specified. They 
have a typical propagation delay of 2 nanoseconds. 74LS series 
chips have a propagation delay of approximately 10 nanosec- 
onds. Some signals must go through three gates, allowing only 
a 6 nanosecond delay with 74F series, or 30 nanoseconds with 
74LS series chips. 

When you purchase your parts, it is unlikely that you will 
find all the 74F chips. It is sometimes hard to find 74F20s. No 
matter, I have substituted all the chips with 74LS series chips 
as a test and it works. You may substitute 74HCT, 74S and 
74LS for all parts except the 74F32. Don't, however, substitute 
a 74S32; the load on pin 56 of the Agnus chip would be too 
high. 

This project has been tested on a normal two-floppy drive 
A500 system with many combinations of parts. If you add a 
hard drive or expand your Amiga in other ways, the extra 24 
nanoseconds from using all 74LS chips might cause your 
system to be marginal. This will show up as random Guru 
messages at bootup. You should try to use as many 74F chips 
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as possible to prevent this. Don't let this scare you. I 
couldn't get this circuit not to work. Go by the book 
as much as possible and you'll have no problems. 

Parts List 

16-256k dynamic ram chips, 
150 nanosecond 41256-15 or equivalent 
1-74F04 hex INVERTER 
1-74F08 quad 2 input AND gate 
1-74F20 dual 4 input NAND gate 
1-74F32 quad 2 input OR gate 
1-74F74 dual D FLIP FLOP 
5-0.1 microfarad ceramic disc capacitors 
1-33 ohm resistor, 1 /8 watt or greater 
5-14 pin soldertail chip sockets 
1 -printed circuit board or 3 inch piece of perf board 
1 -scrap piece of ribbon cable, 6 to 8 inches long 
Wire-wrap wire or hookup wire 
Double-sided mounting tape 



Notes 

An etched and drilled printed circuit board is available 
from the author for $10 postpaid. Send a check or money order 
to Bob Blick, Box 916, Mendocino, CA 95460. 

10 sheets of TEC -200 image film for making printed circuit 
board transfers with a laser printer or photocopier is available 
for $5.95 plus $3 p/h from DC Electronics, Box 3203, 
Scottsdale, AZ 85271, (800)423-0070. 

Substitute for 74F series chips in this order: 
74HCT, 74S, 74LS. Exception: do not use 74S32 in place of 
74F32. 

A501 clone memory boards with four 20-pin 1-meg chips 
will require four of the same generic type of RAM chips 
(514256 type) instead of sixteen 41256 RAM chips. 



About the Author 

Bob Blick is an electronics teacher who also does technical 
work for audio and video studios. He plays drums and enjoys 
watching tennis. Bob has been building projects for the Amiga 
since 1986. He can be reached on MCAB-BBS (707) 937-3056 as 
BOB BLICK and on PLINK as BOFFO'BOB. 
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Accessing Amiga Intuition Gadgets 
from a FORTRAN program 

Using Boolean Gadgets 



by Joseph R. Pasek 

PLINK: OWR821 

CompuServe: 74555,1117 



Introduction 

The implementation of a program on the Amiga can be 
done as simply as the programmer wants — a quick "hack" 
where program inputs and outputs are conveyed by the 
Amiga's CLI. This is O.K. when the programmer wants a quick 
check or something for his personal use. Or maybe the 
program is just better suited if used from the CLI. For those 
programming gems, that may mean many things to a wider 
circle of users. All the obvious indications point to using the 
Amiga's Graphical User Interface (GUI); it should be used as 
fully and as correctly as needed for the application. 

The availability of the Amiga's CLI makes the quick hack 
almost too easy to accomplish. But a piece of software that is 
destined to be used by others and used often should be 
carefully considered as a candidate to incorporate the features 
provided by Intuition. The worthwhile Amiga program 
written in FORTRAN should be no exception to this rule. This 
brings us to the main topic of this article, interfacing a FOR- 
TRAN program to Amiga's ROM Kernel routines. 

The intent of this article is several-fold. First, it is to 
continue an effort featured in the last issue of the magazine 
that shows how to use proportional gadgets from a program 
written in FORTRAN. Here, I will address the use of 
Intuition's Boolean gadgets from a program written in FOR- 
TRAN- Second, I will show an alternative way <>f accessing the 
Amiga's ROM Kernel routines more directly than the means 
provided by Absoft's amiga( ) routine. In a number of cases 
this more direct access enhances the performance of the 
FORTRAN-coded application. And third, I will show some 
programming examples done in FORTRAN that may be useful 
to programmers in general. 

Example Code Description: 
Jupiter's Moons' Simulator 

The vehicle through which I will demonstrate access to the 
Intuition gadgets is achieved with a moderately-sized FOR- 
TRAN-code example. Actually, after seeing the code, you will 
no doubt be quite happy that this magazine comes with a disk. 



This example will provide the more astronomically-inclined 
Amiga-user a reasonably accurate representation of the 
Jupiter's Galilean moons' motion over the next 28 days or so 
days. 

The Jupiter's moons' motion model that is used here is 
taken from Chapter 36 of Jean Meeus' book Astronomical 
Formulae for Calculators, 4th Edition, Willmann-Bell Inc., 1988. 
The described method permits the calculation, for any given 
instant of time, of the positions of the four great satellites of 
Jupiter with respect to the planet, as seen from the Earth. 
Quoting Jean Meeus: "The results are good, but not extremely 
accurate, and therefore may not be used for accurate calcula- 
tions." A more accurate version of the program is in the works. 

The program generates a diagram that is similar to the one 
shown in the astronomical calendar sections of such magazines 
as Sky and Telescope, Astronomy, and astronomical almanacs 
from various sources (Figure 1 provides an example of such a 
diagram). The program completes its depiction of the expected 
motion over the next 28 days. The region to the left of the 
moons' motion graph shows, during the start-up of the 
program, four dots representing moons in motion around a 
stripped disk that is supposed to represent Jupiter's disk. The 
disk shown is a bit larger than the actual perceived disk as seen 
through a telescope (a picture of the screen generated is 
shown in Figure 2). 

This program, written in Absoft's FORTRAN 77, will 
show how to access Intuition's Boolean gadgets, based on the 
newly defined structures in the Premiere Issue of AC's Tech / 
Amiga. In addition, I will describe a machine-language-based 
direct interface to the Amiga's ROM Kernel that is accessible 
from the FORTRAN. Also, it is hoped that the code provided 
will be a reasonable example of writing a structured program 
in FORTRAN. 

The Jupiter Moons' Simulation 
Program Description 

The program is divided into a main program and a 
number of subroutines and functions. The main program 
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Using an alternative way of accessing the Amiga's 
ROM Kernel routines more directly than the means 
provided by Absoft's amiga( ) routine. In a number 
of cases this more direct access enhances the perfor- 
mance of the FORTRAN -coded application. 



JMoGraph5 is the main point of control of the processing. Program JMoGraphS is also 
where most of the graphicat interface is defined and generated, and from where the user 
input is interpreted. Subroutine Makepics( ) is also used to generate the pictures of 
Jupiter and the various positions of the moon for a given date. 

All graphics generated by the program are done entirely by the main program and 
the subroutine Makepics( ). Figure 2 describes the main features of the interface gener- 
ated by this program. 

The subroutine or functions called can be divided into four categories: 

• Direct and Indirect Interface to Amiga's System Routines 

• Astronomical Application Routines 

• Application-Oriented Routines 

• Language System Provided Routines 

In the first category, System Interfacing Routines are all those routines that allow the 
FORTRAN program to access the Amiga's OS and GUI. This includes the means pro- 
vided by Absoft, the amiga( ) routine. The amiga( ) routine can be used as either as a 
subroutine or a function. Its use is as follows: 

result - arnica (SysRoutineName, argl, arg2, ..., arg n) or 
call amlga (SysRoutineName, argl, arg2, ... , arg n) 

where... 

SysRoutineName = Name of Amiga ROM Kernel Routine 

argl, arg2, ... , argn = arguments of a given Amiga ROM Kernel Routine 

The other system interfacing routines that more directly access the ROM Kernel are 
written in M68000 assembly langauge. Some of the routines produced in an ongoing 
effort to implement for FORTRAN programmers a more direct access to the Amiga will 
be described later. The use of these routines serves a couple of purposes. The first is 
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access to the Amiga's system routines with a lot less overhead, 
and, from an esthetic point of view, the ability to eventually 
produce code with a less cluttered appearance that sometimes 
can result by repeated use of the amiga( ) routine. 

Some Jupiter Moons' Simulation Program Details 

FORTRAN is a high-level applications programming 
language. It is possible, however, to write FORTRAN code that 
is capable of interfacing to the various system functions of the 
Amiga and in some ways assume the role of a system language 
like C-language. For those who are familiar with the preceding 
article in this series, it should be clear that FORTRAN 77 
language is capable of performing some of the system-level 
functions that most of us have seen written in C-language. 

In this section I will spend some time to describe some of 
the high-level features of this program. Starting at the begin- 
ning of the JMoGraphS. for code we see the following line: 

implicit none 

This command instructs the compiler to make sure that all 
variables used are data typed. To gain access to the Amiga's 
routines files containing relevant information about the 
systems C-structures, look to constant and routines in the 
include files. The references to the include files in this 
example's code are: 

include execl . inc 
include graph, inc 
include intuitl .inc 
include dakf nc . inc. 

The system data structures defined in the include files are 
treated as "templates" _ they are used to set up a required 
structure. After the structure is defined, the contents of the 
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day period "templates" arrays are copied to another 
byte array. The include files "templates" 
arrays are thus used again and again. 
Since a copy must be made of all 
the structures initialized by the example 
software, a large number of byte (or 
integer*l) arrays are defined. Two 
integer*2 arrays are defined; they will 
hold gadget button background 
(ButtonBack(0:250)) and a representation 
of the disk of Jupiter (ImageArray(0:51)). 

It was decided that information concerning the "Time 
Zone" of the user should be passed as arguments to the 
executable version of the program. This is achieved by using 
Absoft's args( ) routine. The args(cmdline) routine passes to 
the program user's arguments entered at the CLI. The 
subroutine's argument cmdline, a character string, contains the 
arguments the user has entered from the CLI. In a more 
sophisticated application, more code is required to provide 
better extraction of the contents of cmdline than was provided 
here. 

A simple button background (ButtonBack) is defined with 
data to provide a two-color simple button background for the 
gadgets. This array will be later attached to an Amiga Image 
structure. The Image structure will be later attached to three 
separate Gadget structures — one for each gadget. 

The program gains access to the system's Graphics and 
Intuition libraries by calling GfxBase and IntuitionBase using 
the function amiga( ). 

Access to the systems Topaz ROM-based font is achieved 
by setting up a Text_Attr structure which is in turn used by 
OpenFont( ) to open the font. The next part of the code sets up 
the NewScreen structure. 

The NewScreen structure is defined in order to instruct 
Intuition to provide this applicaton with a 640 x 400, hi- 
resolution interlaced screen. To this screen is attached the 
Text_attr structure for the Topaz font. Also, the screen title 
defined by the string variable s_title is attached to the 
NewScreen structure. The function loc( ) is used to return the 
address of a variable that is given as its argument. The 
NewScreen structure is then used by the OpenScreenf ) 
routine. If this call is successful, the system returns a pointer to 
the Screen structure. 

Early in this description, two arrays that contained the 
gadgets background and an image of Jupiter's disk were 
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defined. The contents of these arrays may not be accessible to 
graphics chip, thus the program must get the information in 
these arrays into CHIP RAM. Thus the need for the process 
described in the next paragraph. 

Allocation for CHIP RAM is made in order to store the 
image data for the gadgets and Jupiter's disk model, A call is 
made to AllocMem( ) for each image array, providing the size 
needed and making the provision that it be from CHIP RAM. 
AllocMem( ) for each call returns an address, if successful, to a 
region in the CHIP RAM that has been allocated to these 
image-defining arrays. The image data is then written to the 
allocated CHIP RAM. Word( ), a FORTRAN provided func- 
tion, permits the program to read and write two byte chunks of 
memory at a time. The FORTRAN system also provides byte( ) 
and long( ) functions to allow the programmer to directly read 
and write memory location in one-byte and four-byte chunks. 

A good portion of the code from this point on is spent on 
setting up the necessary Image, Gadget, Border, and IntuiText 
structures for graphic items that will appear in the window. A 
familiarity with Amiga's C structures as defined in the 
Amiga's ROM Kernel Reference Manuai is all that is needed to 
understand what is shown in the code. 

The NewWindow structure is next defined for this 
application and once defined is used by the OpenWindow{ ) 
routine to open the window. If successful, a pointer to the 
newly-defined window structure is passed back to the calling 
program. 

The routines date( ) and time( ) are called to get the 
current date and the time in seconds from midnight as defined 
by the system's clock. This time is the starting point of the 
calculation of Jupiter's moons' positions. The current date as 
provided by the Amiga's system clock requires the users to 
provide their time_zone as an argument to this program's 
executable form; i.e., jupmoons 

time_zone = 8, for Pacific h^^^^^^^^^^^^^h 

Standard Time zone. 

The next section of code 
generates the graphic the user 
will see. Most of the window's 
graphics are generated "on-the- 

fly." The main title "Jupiter's 

Moons' Motion Simulator" is 
done using 25-point Times font 
that is normally found on the 
extras disk and should be in the 
user's fonts directory. The Times 
fonts is a disk-based font and the 
system's OpenDiskFont( ) is 
needed to access it. The 
OpenDiskFont( ) is accessed 
using the Absoft's amiga( ) 
routine. 



The SetFont( ) routine is used to assign the font to this 
applications window's RastPort. SetRGB( ) is called to re- 
define the contents of the screen's color registers and 2. 
SetDrMd{ ) is then used to set the drawing mode for the 
window, in this case "J AMI". The variable "string" is assigned 
the character string that makes up the title. 

An example of an application-oriented routine is the 
FORTRAN subroutine called bwrite( ). Subroutine bwrite( ) is 
a specialized routine that is capable of generating either a 
"balloon," "outline," or two-color font effect for a given font. 
The outline of the font would be in one color and the main 
body in another. Use of the shift argument could give a balloon 
effect. It is not very sophisticated but does a nice job. The 
bwrite{ ) code is now given to review: 



subroutine bwrite (port, string, 
* colorback, colorf ront) 



xloc, yloc, shift. 



* port - Current window rast pointer 

* string ■ character string being passed 

* sloe, yloc - coordinates of position 

" shift = number of shifts the character string is 

* spread around 

* colorback - color register number for outline color 

* colorfront = color register number for !r.ain body color 

implicit none 

include graph. inc 

include intuit. inc 

character* (') string 

integer"* shift, colorback, colorfront, xloc, yloc, 

+ X, yy, n, i,j 
xx - xloc 
yy » yloc 

n = len (trim (string)) 
call SetAPen I long (port), colorback) 
do (j - -shift, shift) 
do (i - -shift, shift) 

call FKove (long (port) , xx-I, yy-j) 

call Text (long (port) , string, n) 
enddo 
enddo 

call SetAPen llong (port), colorfront) 
call FKove (long(port), xloc, yloc) 
call Text (long(port) , string, n) 
return 
end 
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integer RectFill 

parameter (RectFill = z'0007F233') 



This field describes RDM 
Kernel routine's argument 
sequence. 



This field points to the 
library routine, in this 
case the library is 
the graphics library 



This field provides the 
offset from library base 
to routine. 



The font is removed from the window by calling 
CloseFont( ) and then removed from the system font list by 
calling RemFont( ). 

The font associated with the window is again changed, 
this time to 15 pt. Times. More text is generated, but the text 
generated is accompanied by a shadow effect. This effect is 
generated using another FORTRAN-based routine — 
graphwrite( }. Since graphwrite( ) is a relatively short program, 
it too will be shown here for the reader's review: 



subroutine oraphwrite (pott, string, xloc, yloc, 
+ shift, colorback, colorfront) 

This routine generates a shadow-like effect for a 

given font. 

port = windows rastpointer 

string = character string containing the tent to be displayed 

xloc, yloc = window coordinates where the text 

will be place (ULHC! 
shift = length of shadow 
colorback ■ number of color reg. that Is used for 

the shadow 
colorfront - color reg. number that is used for 
the font . 

implicit none 

include exec. inc 
include graph. inc 
include intuit. inc 



character*;*) string 

integer*4 shift, colorback, colorfront, 
+ xx, yy, n, i 



iloc, yloc. 



XX 

yy 



xloc 
yloc 



n = len(trim(string) I 
call SetAPen (long (port) .colorback) 
do (i = shift, 1,-1) 

call FMove (long(port), xx-i, yy-i! 

call Text (lang(port) /String, n! 
enddo 
call SetAPen (longlport ), colorfront) 
call FMove (long(port), xloc, yloc) 
call Text (long (port! , string, n) 

return 
end 



Figure Three 

Absoft's Encoding 
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Examining the JMoGraph5 routine, the reader can see that 
repeated use of the above subroutine is done to set text down 
on the screen. 

The user should have noted that some additional routines 
in some cases have names that are identical to ROM Kernel 
routines. These assembly language based routines are used to 
directly call the ROM Kernel routines. Move( ), Draw( ), 
RectFillf ), SetAPen( ), DrawEllipse{ ) are comparable to the 
Amiga's Graphics library routines. The argument list for these 
FORTRAN interface routines are identical to the similarly 
named versions described in the ROM Kernel Reference 
Manual. 

After generating some more text on the screen, the 
variable time_since_midnight, which stores the time in units of 
seconds, is changed to units of hours. The correction for 
epheremis time is done using the year value (Subroutine 
UTtoET( )). Combining the day, with ET corrected time, and 
Time_Zone yields the corrected day (rday). Julian day (JD) 
number is generated from the date and time (subroutine 
Julian( )). 

Variables are initialized. The range of days (JD_begin and 
JD_end) that the moons will be plotted over is also determined. 
Again, all times are done in terms of the Julian Day number. 
Graphics depict the moons' motion as viewed from a simu- 
lated telescopic view and the motion of the moons as viewed 
from below the moon's orbital plane (viewing the moons' 
motion from over Jupiter's south pole). This bit of processing is 
accomplished with the FORTRAN'S while-repeat loop. 

The while-repeat loop is used to control the initial 
graphics animation. The time-increments between each frame 
drawn is set to one hour. The subroutine JMoons( ) provides 
positions of Jupiter's moons for a given time — time again is in 
terms of the Julian Day number. 

Let's examine some of the other components of the while- 
repeat loops. As the moons' trajectories are plotted, the 
corresponding date and hour line is generated. The subrou- 
tine JDtoCAL( ) is used to convert the JD number to a calendar 
date. The four moons' positions (X, Y, Z) are plotted using the 
appropriate color, set by calling SetAPen( ) and drawing 
segments of the trajectories using repeated calls to Move( ) and 
Draw( ). 
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In the area to the left of the moons' trajectories, plots of the 
moons' positions are shown as viewed from above the planet's 
south pole (upper) and as viewed through a telecope at low 
power (lower). The planet's disk is re-drawn each time using 
the routine Drawlmage( ). The moons are depicted as color- 
coded 2x2 rectangles and are drawn and undrawn using the 
RectFill( ) routine. This is how the initial display of the 
program is generated. 

After completion of Jupiter moons' 28-day trajectory plot, 
the window gadgets defined earlier are added to the window 
with a call to the function AddGList( ). To activate the added 
gadget in the window, one performs a call to the system 
routine RefreshGadgets(). Four gadgets should be displayed: 
"Rewind," "Stop," "Start," and "Quit." Except for the "Stop" 
gadget, all of the new gadgets are active. The Stop gadget is 
ghosted and inactive. This is achieved by calling the system 
routine OffGadget( ). Another defined gadget coincides with 
the area of the moons trajectory plots. 

The do-while loop that follows contains all of the interface 
code to the user's gadget selections. Since the window has a 
close gadget - class = CLOSEW1NDOW, a click there is 
indicative that the user desires to close it all down. A message 
with a message class corresponding to GADGETDOWN starts 
the processing to identify the selected gadget by means of its 
assigned GadgetlD. 

For instance, the large gadget that corresponds to most of 
the area of the moons' trajectory plot, if selected, generates a 
GadgetlD = 1. If this gadget is selected, the mouse position 
(mx,my) is extracted from the window structure. From the 
"my" component of the mouse-pointer position, the date and 
time are computed. A call to MakePics( ) is done to update the 
moon positions in the left two displays. The "Stop," "Rewind," 
and "Start" gadget appearance are now adjusted accordingly 
— "Rewind" and "Start" are active and "Rewind" is inactive. 
This is signified by the gadgets' ghosted appearance. 

The "Rewind" gadget has a GadgetlD = 2. If the "Rewind" 
gadget is selected, the current Julian Day number is initialized 
to hour UT for that day. Each additional click on this gadget 
backs up the JD number by 24 hours. The MakePics( ) routine 
is called again to modify the views in the left two windows. 

If the "Start" gadget (GadgetlD = 4) is selected, a sequence 
of images is generated to show the moons' positions for a 24- 
hour period. Each image is formed at 0.1 hour intervals — a 
total of 240 images. Thus we have an animation of the moons. 
During the period of this animation, the "Rewind" and "Start" 
are inactive (gadgets are ghosted) and the "Stop" gadget is 
made active. 



If the "Stop" gadget (GadgetlD = 3) is selected, the 
animation is stopped. The "Start" and "Rewind" gadgets are 
again made active and the "Stop" gadget is made inactive. 

If the user does not elect to select the "Stop" gadget during 
the animation and allows it to finish, the control gadgets are 
again made active and inactive as needed. A code segment 
from the example shows a little of what is being done here: 

else if ( GadgetlD - 4 ) then !User selected Start gadget? 
call OnGadget ( loc (Gadget_Stopl , Window, 0) 
call OffGadget ( loc(GadgetRewind) , Window, 0) 
call OffGadget ( loc(Gadget_Start) , Window, 0) 

! show moons positions over 24 hour period starting within 
! date resolved from trajectory plot. Time step ■ 0.1 hrs. 

do ( i - 1, 240 ) 
call MakePies (port, InagePtr, JD, X, if, 2, OldXX, 
+ OldYi, Oldzz) 

message = GetMsg (long(Window+wd_UserPort) ) 
if ( message <> ) then ! User has selected a gadget 
call OnGadget (loc (Gadget_Rewind) , Window, 0] 
call OnGadget (loc(Gadget_Start) , Window, 0) 
call OffGadget (loe(Gadget_Stop) , Window, 0| 
class = long(mes5age+im_Class) 
code ■ word (message + im_Code) 
GadgePtr - long (message + im_IAddressl 
GadgetlD - wordlGadgePtr + 38) 
call ReplyMsg (message) 
if (class = GADGETDOWN) then ! User hit STOP gadget? 

if ( GadgetlD » 3 ) exit ! if so exit do-loop 
endif 
endif 

JD - JD + 0.00116667 ! increment by an 1/10 of hour 
enddo 

call OnGadget ( loc(Gadget_Rewind) ,Window,0) ! Enable and 
call OnGadget ( loc (Gadget_Start) , Window, 0) ! disable 
call OffGadget ( loc(Gadget_Stop) , Window, 0) ! gadgets endif 

If the "Quit" or "CloseWindow" gadgets is selected, the 
do-while loops is exited by toggling the logical variable 
"Waiton" from TRUE, to .FALSE.. The calls to CloseWindow( ) 
and CloseScreen( ) close the window and screen respectively. 
Calls to the FreeMem( ) routine returns the earlier allocated 
memory back to the system. The fonts are removed from the 
system font list using a call to the RemFont( ) routines. This 
concludes the description of the main program. 

A Modified Interface to the 
Amiga ROM Kernel routines 

As alluded to earlier and as the reader should have 
observed while looking at the example code, some of the calls 
to the system routines come in one of two ways — the more 
direct means, call Draw(port, x, y) or the indirect way, call 
amiga( Draw, port, x, y ). The amiga( ) routine was provided 
by the maker of this FORTRAN compiler — Absoft. 



Volume 1 , Number 2 



81 



integer CBump 


/parameter 


integer InitView 


.-parameter 


integer SetDrMd 


.■parameter 


integer SetBPen 


.-parameter 


integer SetAPen 


.■parameter 


integer PolyDraw 


.-parameter 


integer Flood 


.'parameter 


integer WritePixel 


.■parameter 


integer ReadPixel 


.•parameter 


integer BitPattern 


.•parameter 


integer RectFill 


.■parameter 



The amiga{ ) routine is a really nice bit of coding — 
machine coding, that is. The routine essentially takes care of 
interfacing the FORTRAN to the Amiga's ROM Kernel. The 
Absoft include-files provides descriptions of structures and 
system constants, and takes ROM Kernel routine names and 
assigns each one with a unique number. Each include-files 
contains something like the following list: 



(CBuir.p =2'0000923D') 
(InitView =z' 0000923C ) 
(SetDrMd =z' 0021923B' ) 
(SetBPen=z'0021923A' ) 
(SetAPen=z' 00219239 ' ) 
(PolyDraw =z' 02219236 ' ) 
(Flocci -z' 8C25923T) 
(WritePixel =z' 04619236 1 ) 
(ReadPixel=z # 04619235 ' I 
(BitPattern = 2' Q009F234 ■ ) 
(RectFill =z' Q007F233') 



Let's examine a single line from this list. On the left side of 
the list, we see variable names data typed as integers ( 32 bit ). 
To the right of each typed variable appears a parameter 
statement in which the typed variable to the immediate left is 
defined with some hexidecimal number. 

The listed variable name corresponds to the name of a 
ROM Kernel routine. The value assigned to it by the parameter 
statement is an encoding of everything that is needed by the 
amiga( ) routine in order for it to interface correctly with ROM 
Kernel routine (see Figure 3 for a closer look at the meaning of 
the numbers assigned by the parameter statement). 

Each time a ROM Kernel routine is cailed using the amiga( 
) routine, a significant number of operations is required before 
the actual amiga( ) routine is called. This approach is a 
reasonable one if the call is made infrequently, such as to 
OpenScreen( ). Often, the need is for calling a ROM Kernel 
routine repeatedly at a high rate, say while performing certain 
graphic functions. In the example discussed above, calls to the 
ROM Kernel graphic routines RectFill( ) and Drawlmage( ) are 
made very often in some parts of the main program and again 
in the MakePic( ) subroutine. In these cases a more direct 
approach using FORTRAN'S capability to access machine 
language subroutines and functions is better. 

In the example, a number of ROM Kernel routines were 
called in the more direct manner. However, few of the calls 
were accomplished using Absoft's amiga( ) routine. 

"So just what do these nifty, more direct calls procedure 
look like?" you ask. Well, here are some examples (more are 
located in the file F77Interface.asm), The first example shows 
the RectFill( ) routine which interfaces to the similarly named 
ROM Kernel Routine. 



* FORTRAN calling sequence 

* call RectFill (rp, x, y, xsize, ysize) 

* 

* assembly language source for a FORTRAN callable routine 

* that calls the Amiga's graphic RectFill ( ) routine 

_RectFill equ -306 

RectFill: movem.l a0-a2/a6,- (a7) 
movea.l 4 (aO) ,a6 

movea.l 36<a7),a2 ; load RP pointer 
movea.l 32(a7),al ; y. position in RastPort 
move. 1 (al) , dO 

movea.l 28 (a7) ,al ; y position in RastPort 
move.l (al) , dl 
movea.l 24(a7),al ,• x LRHC 
move. 1 (al) ,d2 
movea.l 20(a7),al ; y LRHC 
move.l (al) , d3 
move.l (a2),al 

jsr _RectFill(a6) 

movem.l (a7) +,a0-a2/a6 
rts 

end 



Rectfill( ) is a graphic library routine. Absoft's FOR- 
TRAN77 when-if calls a subroutine first, puts the program 
counter on the stack followed by the first argument — in this 
case the rp (RastPort) — then followed by the coordinate pairs 
of the Upper Left Hand Corner and Lower Right Hand Corner 
of the rectangle object desired. When the RectFi!l( ) routine is 
finally entered, some of the registers used by this routine are 
also placed on the stack. The next instruction sets up register 
a6 with the appropriate library base address. The remaining 
steps access the contents of the stack to get the addresses of the 
various parameters passed through the calling sequence. The 
locations at these addresses are accessed and the contents are 
transfered to the appropriate register as required. Once the last 
step is finished, a call to the ROM Kernel routine is done. 
Before the return from this routine, the content of the registers 
being saved on the stack are restored. 

Another example shows the assembly language version of 
the routine used to direct access the ROM Kernal's 
Drawlmage( ) routine. 



FORTRAN calling sequence 

call Drawlmage (rp, Image, LeftOffset, TopOffset) 



* assembly language source for a FORTRAN callable routine 

* that calls the Amiga's Intuition's Drawlmage routine 



_DrawImage equ -114 

Drawlmage: movem.l a0-a3/a6,- (a7) 

movea.l B(a0),a6 ; Set up base for Intuition Library 
movea.l 36(a7),a2 ; load RP pointer 
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movea.l 32|a7),a3 ,* load pointer to Image structure 

movea.l 2B(a7),al ; load LeftOff set 

move.l (all, dO 

movea.l 24<a7),al ; load TopOff set 

move. 1 lal ) , dl 

move . 1 (a3) r al 

move. 1 |a2 ) ( aO 

jsr _DrawImage (aS ) 

movem.l (a7> +, a0-a3/a6 

rts 

end 

This routine is a member of the Intuition library. The 
procedure is the same. Save the contents of some of the 
registers on the stack, set register a6 to the intuition library 
base, access the stack (see Figure 4) and get what is stored 
there — addresses. The contents of these addresses are 
extracted. Once completed, the intuition library's Drawlmage{ 
) is called; upon return, the old register values are restored off 
the stack. 

Additional examples of assembly-language-based routines 
that allow a FORTRAN program to access the Amiga ROM 
Kernel are located in the files F77Interface.asm on this 
magazine's accompanying disk. If you study the source code, 
you will note that some of the routine names do not match 
ROM Kernel routine names. An example of this is the routine 
ScToBk.asm , which is the direct access to the ROM Kernels 
ScreenToBack( ). The Absoft linker only looks at the first six 
characters of routine names. Care must be taken in assigning 
names that are unique in the first six characters. For instance, 
another routine in the Intuition library is ScreenToFront( ). 
Maybe Absoft in the next upgrade release will allow the linker 
to accommodate more characters in the program's name. 

Conclusions - The Big Wrap-Up 

As in the previous article, I have attempted through 
example to show the Amiga FORTRAN programmer how to 
interface to the Amiga Intuition's Boolean Gadgets. I showed 
how to control the program's processing in response to gadget. 
Again, the programmer must make sure he has the modified 
exec and intuition include files found on accompanying disk in 
order to have the gadget structures and defines needed to use 
Intuition gadgets. 

In the next article in this series, I will address the use of 
string gadgets. 



Listing One 

JMoGraph5.for 



c JMoGraphS.for Sept- 2B, 19&0 / Revised Jan, ID, 1991 
c Copyright © 1991 by J. ft. PASEK 



c This prog-ram computes the location of Jupiter' s noon 

e with r&apect to Jupiter and in units Jupiter radii. 

c Mg&rithraa for Jupiter Moons position come fron "Astronomical 

c Fornul&e toj Calculators*, by Jean Heeus, Willnann-Bell, 1935 



program JupMoons 

implicit none 

include execl.inc 
include graph. inc 
include intuitl.inc 
include dskfnt.inc 

charact»r*3Q tenant 
character *50 s^title 
charact*r*5Q w title 



t Force all variable to be dats tyeped 



! font name 
! screen title 
! window title 



integer amiga.loc ! declare the functions 



integer Screen 
integer Window 



integer message 
integer class 



! pointer to "Screen" structure 
! pointer to "Window* structure 

! IntuitionKessaga 
! la Class 



integers GetHsg, OpanWmd, OpenSe, AllocMea, ArfdGList I factions typed 

integer" 4 gad_positicn, InageBacfcGr 

integer iteap, result, one 

integer'4 i.purt.color.x.y.xx.yy, ImagePtr 

logical Waiton 

integer** foot, font25 f fontn, EOBtU r tepazfant 

int*ger*l Gadget_Rewind(44| , Gadget_Stopmi, Gadget_StarM44), 

1 Gadgat_Abova(44), Gadget_Qu.it (44) , ChartjGadget744>, 

2 BorderQ[lfi}, Qteit|20], 7cpa:TexUttr(6)7 

3 RewTextUQ), StopText (20), StartTeit{20), Icagesack(20) 

integer f 2 IsageArray(0:51} ! Jupiter Disk iMge Data 

:nteger*2 3uttDn3acjc(Q:250} ! Button Background 

integer *2 3ordVectorsQ(10>, code, Gadgetl&, BordVectcisMlGI 

integer** GadgePtr 

character MO string, oldstring, Qstring, RewString, StopStiing, 
* StartString 
character* 30 IDstring, aadline 
character"L2 Kusstr, TimeJIane_Sti 

int.«ger*4 day_crit, rstep, Oldistep, icnt, icnt_day 
integer* 4 aonth, day, year, t_ae_3ir.ce_mdr.:ght, n 
nal-4 rday, tiMjuux, £T, delT, X{4), Y|4), u|4), uc(4), 
+ 01dX(4|, 01dY(4J, OldXXM), OldYYH), temp, 

+ old:: (41, ti»_im« 
real-4 *l*ne(4), Z(4),~¥Y(4} 

integer'4 oldloc:*, c-ldlc-cy, oldloc-t, loci, locy, loet 
real*S JD, 6, dddel, JIMnd, JD_begin 

integBr"4 ipiageBLocfe, siie, siiel, flags, IA 

int«g«r*2 nx, ay ! souse position coordinates 

' Following data statement defines an approximate Jupiter mage. 

data ImagaArray fll*z' ttti' , 
I z'OSeDM'OffS'.i'iffe'.z'If&f'.z'TfOf ,z f 7£9f*,z'7ffe\ z' 7:ie' , 

3 i'7ffe',i'7ffB',E'3ffe',i , OffBM'0iet)\ 

4 2*z'0 , r i'3_f**,3*i'0 , ,i'7fff , ,3»i'0*,i , 3ff»' r 2*2 F 1 , 

5 z'OSeSVz'QriB'rZ'Srie'.z'Tffe'.z'lfie'.i'Tfre', 

6 i'7ff«',t'7«4t',x f 7ff»',t'7ffa' 1 i'3ff«',i'Offfl , ,i'03B0 7 

data BordVectorSy/0, 0,4.0,0, 40, 15, 0, 15, 0,0/ ! Border for "Quit" Gadget 
call args (caidline) 1 Get Ca^Eiand-lifiH information 
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read (cEdliAs,"(4l2» 13)") TiM_Zcr.Q_Str, Tixa^Zcna tExtraet cad line 

! information 
write (9, "(A, 15) "J Ti=e 2cne Str, Tisa Zone 



! Set*up Button Background 



one - ] 

do (i - 1, 15| 
ButtcnBackUi-l|*$) - x'fiff 
EuctcnSacMU-l)*<+l) - i*£f£f* 
ButtonBacM{i-l)*4+2) - t'tltV 
EuttcnEacfc(U-I|*4+3) - z'fffS' 

er + idc 

5uttcnBack|6t))*0; ButtanBacX|61)'*0; ButtonBack (62H0 

BttttOflfiackl€3J«fl 

do (l - IT, 291 
ButtonBack((i-l)M) * l'lttf 
B'jttonBack((i-l)**+l> » I* MM' 
Button3ack((i-l)M+2) - l'lttf 
fiuttor.9aek((i-l)M+3) ■ z'ffiO 1 

enddo 

BuczonSack{116)*0; Button3ackU17)-Q; Suttofi&ack(lll)-C 

Buttcn=acfc(ll9)"Q 

do (i ■ 31. 60) 
3uttonBack||i-l)*4] - D 
ButtonBackl (i-l)*4+l) -Q 
ButtonBack(|i-l)*4+2| - 
ButEonBack((i-l}M*3] - 

enddo 



ISstring - 'Program by; J. ft, FA5EK, 3210 S, Diamond St., 
I3string - iDstring//' Santa Ana, CA 92704' 



i - assiga(Gf xBase) 

if (i-0) stop ""GfxBasa' failed* 



open "graphics, library" 



i - a^-igadntuitionBase) 

if ( i-0 ) atop "IntuitionSasB failed" 

- Mt -p the screen text style 



tjtim - " % tspii,font"//char(0} 

taJJaa* - loc(f_naa*! 

ta_YSize - B 

za_S=yU - FS HOHQL 

ta_riags - ^jii'j:::: 

font " anuga (CpenFcnt t T*xtAttr] 

if ( font * ) atop "Stop, Tcpat font not available.* 

topaz feat - font 

set us t&e I'evSsreen data block and allocate the screen 

s_titie - ""he Amiga Astronomical Almanac by J,R, JASEKV/char {Q| 

ns_Le:tEdge ■ 
ns_TopEdge - 
ns_Hidth - 610 

ni_H*ight - 400 

ns_Depth. - 4 

m_Detfl],iPen - 

ns_3lcck?en ■ 1 

ns_Vi6KModes - HIRES .or. LACE 

ns~Typ« - CU5TGHSCAEEH 

ns_Font ■ loc(TextRttr| 

ns_Def Title - loc(s_titla) 

ns Gadgets ■ 

ns~CuscBitMap ■ 

Screen - QpenSc ( NewScrean) ! Open Screen 
if (Screen-Oj stop "'OpenScreen' failed" 



ta_5tyle ■ FS_B3L3 

do ( i - 1, 8 ) 
TcpaiTextAttr (i) - TextAttrU) 
enddo 



' Define font 

! Copy Text At EI 



call ScToEk [Screen] ! Place Screen to back of rest ScreenTo&acfc 

size - 230 ! Allocate CHIP RAM for Jupiter Xsage 

flags - WBStJXa 

InageBlock - AllocHen (size, flags) 

if ( laagefllock * | atop "Unable to allocate aeuory* 

size: - fiOO ! Allocate Cillr RAft for Gadget Backgrounds 

IsageBackSr - Al.c-.Xa- (size!, flags) 

if ( Iaaje5acs5: - ! step "Unable to allocate msory' 



do ( i ■ 0, 51 ) ! vrite Inage data to chip ran 

Mord(Itageaiock-2»i) - I;rageArray|i| 

enddo 



do I i - 0, 236 ) 
woid(:;cageBackGr-2"i) - ButtcnSackli) 

enddo 



c set-up inaga structure for Rewind, Stop, Start buttons 

ig_LeftEdgo * 
ig_CopEdge - 
igjfidth - 60 
ig_Keight - 15 
igjltptb « 4 

ig_lB3geData ■ I^ageBackGr 
ig_EIanePiCk » z'f 
ig_Pla.-.eQr,Off - 
ig_ttextlr^ge - 



do < i - l r 20 ) 

IcageBackli) ■ Inageli) 

enddo 



! Copy Image structure tei=plate to ijaageBacfc 



set-up the noon's trajectory vlndow gadget structures. 
The whole area is one big boolean gadget 

ggjloxt Gadget « 
gg_LeftEdge - <4< 
gg_TopEdge - I 
gg~Hidth - 110 
gg_Keight • 366 

oa_Flag5 - GADGHBOX 

og_Activation * RELVE-RIET -or. GADG IMMEDIATE 

ggJSadgetType - BOOLGADGET 

gg_GadgetRender - 

gg_Select Render - 

gg_MutuaiExclude - 

gg_GadgetText - 

gg^Speciallnfo - 

ggjEadgetID «* 1 



do | i - 1, Ai 1 
Chart_Gadget(i) ■ Gadget li| 
end do 



Copy Gadget structure, teaplate to Chart 



Set-up another Close or Quit Gadget in the Hindew 



bdLafcEdca— 1; bd_Top£dge— 1 
bd Frcr.tEen-3; fcd_BackPen"0 
b4J3ra¥Hcde-JAHl; bd_Count-S 
bd_xv - IcclftordVectorsQ) 
bd N'extBcrder ■ 



Quit Gadget's Border structure 



do < i • 1, 16 ) 
BorderQ (i) - Border {i) 

end do 



! Hake copy of Border structure 



5et-up gadget to Rewind to o tours UT 

RewString - "Rewind"/ /char (C| ! Rewind gadget's intuitext structure 

it^Frontfen - T; it_SacxPen ■ Oj it_DrawHode-JAMl 
it_LeftEdce - 3; it~TopEdga - 1 
it_I7flstFcnt ■ loc(TopiaTaiitAttr) 

itIXRXt - lec (RewString) 
it_HextTejst - o 

do ( i * I, 20 ) ! Copy IntuiTex: structure 

RawTextlil - Ir.tuilext li) 

end do 

gg_KextGadget - loc^hart_Gadgat) ! All Gadgets are linked together 

gg_Left£dce - 250; gg_TopEdge - 280 ! This ia the Rewind Gadget structure 

gg_Width - 60; gg_Height - 15 

gg_Flags - GAI>3HCQHP .or. GADGIMAGE 

gg_Activation ■ RELVERIFY .cr, QADGIHHEDIATE 

gg_GadgetType - BOOLGADGET; gg_GadgetRender - loc(ImageBack) 

gg_5el act Render ■ 0; gg_GadgetT*Kt - loc(fie»fT«xt) 

gg_KutualExclude - 0; gg_SpecialInco - 

gg_GadgetlB - 2 



Hake copy of gadget structure 



do < i - 1, 41 ) 

Gadgfit_Rewir,d(i) - Gadget (l) 
end do 

- Set-up gadget Stop 



Sccp5tring * *SIO?V/char|0) ! Following is IntuiText structure 
! for Stop gadget 

lz_riantptn ■ i; li_5acXPen - 0; it_0rawK:2e-;AM: 
it^LeftEdga « 3: it_TopEdg* - 2 
it_n#Jttr«rt - loc(TopazTextAttr) 
it_IText - lo= (StopString) 
it_Bextr«xt - o 

do t i ■■ 1. 20 ) ! Copy Intultext structure 

5tapT*jtt(i| - IntuiText {i) 
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end do 

gg^EIext Gadget H locfGadget^Re'wir.dJ ! This is the Rewind gadget structure 

gg_LeftEdge " 250; qg_TopEdge * 30° 

gg_Kidth - 60; gg_Keight - 15 

9g_Fla9S - GADGKCCHP .01. GACGIHAGE 

gg_Activaticn - RELVERIFY .or. GADG1HHEDIATE 

gg_GadgetType ■ BOOLGADGET; ggjGadget Render - IccflicageBack:) 

gg_SelectRer.der * 0; ggjSadgetText ■ ioc(StopText) 

gg_KutualExclude ■ 0; gg_SpecialIn£o - 

gg_GadgetID • 3 



do i i m l t 44 ) 

Gadget_Stop(il - Gadget Ul 

end do 



Make copy of gadget structure 



Set-up gadget Start 

StactStrirtg ■ "StartV/charJO) ! Start gadget's intuitext structure 

it_FrcntFen - 7; it_Bac)cPen - 0; it_DrawMcde-JAMl 
it~Lef^Edge - 3; itJEcpEcge - 1 
it_IteKtFor.t ■ IccJTopazIextAttr) 
it~Itest - ioc(StartString) 
it KextText - 



■:■; 



i - I, 20 ) 



StartText(i) - IntuiTextU) 
end do 



Malta copy of gadget intuitejct 



cc_tfej,t Gadget - Ioc (Gadget jStcp) ! Start gadget's structure 

gg~LeftEdge - 250; gg_Top£dge - 320 

ggjfidth - 60; ggJSeight - 15 

gg_Flags - GADGKKQjrE .or. GADGIKAGE 

gg_Activation • RELVERIFY .or. GAEGIMMEDIATE 

gg_GadgetType - EOOLGAEGET: gg_Gadg at Render - lccdnageBacii) 

gg^SelectRender * 0; ggjSadgetText ■ ioc|5tartText) 

gg_HutualExclude - 0? gg_SpecialIr.fo - 

gg_GadgetID - 4 



(to C i - 1# « I 

GadgetjStart li) - Gadget (i) 
end do 



Qstring - "QUIT"//char(0) 



Hake copy gadget structure 



! Quit gadget intuit eat structure 



it_Frantffln « 3; it_Bacicpen"0; it_Dra,vMode=*JAM2 
it_LeftEdge - 3; it_TopEdge - 1 
it_I Text Font « lcc(TopazTeXtAttr) 
it_I~ext • loc(Qstring) 
it UextText - 



do ( i - 1, 20 ) 

OCvxcUi ■ Inttu.T*KE 111 

end do 



t Make cop/ of intuit ex t structure 



ggJJextGadget ■ Ioc (Gadget_Star£) ! Quit gadget's structure 

gg_LeftEdge - 250 

gg_TopEdge - 345 

gg_Width • 40 

gg_Height ■ 15 

gg_Flags - GADGHCOK? 

gg_Activatlon » RILVIRIFi" .or. GADGIMMEDIATE 

gg_GldgetType - BOOLGADGET 

ggjSadgetRetidet - Ioc (Border. OJ 

gg_Select Render e 

gg_GadgetTest - loclQtext) 

gg_Mutu.alExclude ■ 
gg_Specia!ln£o - 
gg_GadgetIP - 6 



do | i - 1, 44 1 

Mii-.-t ;Mit(i) - j.iJ'jet[i| 
end do 



- set up the JlewWindqw data block 



Hake copy of gadgat atructun 



w_title - "Jupiter Moons Positions (FKELIHEDASVr// char(Q) 



nw LeftEdge 


- 1 


nw TopEdge 


- 15 


nw Hidth 


- 639 


:;w Height 


- 330 


nw DetailPen 


- 


nw 31oci(?en 


- 1 


nwjriUe 


- locjw title) 


nv_rlags 


- WINDOWCLQSt .or. SMART REFRESH 


,or. 


GIJWEZErtOZE&O 


nw IDCMPrlfflgj 


- CL051WINUOW .or. (5ADGETDQ1TN 


nw Type 


- CUSTGHSCREEM 


nw FirstGdgt 


- ! ioc (Chart Gadget) 


nw CheckMaEk 


- O 


nW Screen 


- Screen 


nw BitMap 


- 


nw MinHidth 


- 100 


nw^MinHeight 


- 25 


nw MaxKidth 


- 640 



.or. ACTIVATE 



nw_MaxEeight *■ 3B0 

Window = OpenWind (KevWindow) 

if {Window=0} ttteft 

call CioseScreen (Screen) 
stop "'Opentfindov" failed" 
endif 

port ■ Window twd_RF0rt 

O set-up image structure 



Open Window on custcuscreen 



t Get pointer to window RasterPort 



ig_LeftSdge - 
ig_TopEdge - 
ig_Width - 16 
ig_Height - 13 
ig_Depth - i 

ig_InageData - Iaage3lock 
ig_PlanePick ■ i'f' 
ig_PlaneQnOff « 
ig_yextlnage - 

iMgeFti - Ioc (linage) 



! Jupiter Inage • Inage structure 



Get pointer to Jupiter Inage structure 



call date (month, day, year) ! Get current date 

.:;.1_ tine [tine_smce_aidmght) Get "'-.zz-jz'. tlM t::r. IffftU 



! Define Teit/Font Attribute structure 



Tstep • 5 
OldYstep ■ 5 

* - set up the text style 

* call CloseFdnt (font) 

r_naaie » "Tinas. £ont"//char(D} 

ta_Haaa ■ loc(f^name) 

ta^YSize - 24 

ta_Style - FS_30LD 

ta_Flags - FP_DISKFOHT 



font = aaiga (Ope.-iOiskFont, TextAttr) ! Open a disi: based font 

if ( fane - )■ then ! If unable to open disk font exit 

call CloseHmdow (Window) 

call CloseScreen (Screen) 

call FteeMe.M (XmageBlocx, size) 
stop "Stop, Tifces 25 not available.™ 
endif 

font25 ■ font 

call SetFont (long (port), font} 



Assign font to window 



call S«tRGB <ScE44n+0£_Vi»ui>G!i:E l O,lQ,lG l lO) I R*-defina color r«gist*r 
call SatRGB (ScraBn+sc_View?ort ( 2 ( 3 ( 5 ( 12) I * 2 

call SetDrHd (long(port), JAH1) ! Set Drawing Mode 

string - "Jupiter' s Moons Motion Simulator" 

call bwrite (port, string, 12, 22, 1, ?, 11) '. Routine generates two 
! color font 



set up the text style 



call CloseFont (font) 

call RemFont (font) 



f r.a.r.9 



! Close Tines 25 font 
! Removes Times 25 font from font list 



! Set-up Taxt Attr. Struct for 



iaies . f ont"//ehac (O) 
! Tines 15 font 
taJKana = loc(f_inaffie) 
ta^YSize - 15 
ta'style - FS_HOaKK. 

ta_Flags ■ FP_DISKFOKT 

font ■ amiga (OpenDiskFont, TextAttr) ! Open disk based font 

if ( font = ) then ! If not available clean-up, exit 

call CloseWindow (Window J 
call CloseScreen (Screen) 
Call Fcerfteci (IrnageBlock, size) 

stop "Step, Tines 15 font not available," 
endif 

fontl7 - font 

cail SetFcnt (long (port), font) 



Assign font to window 



string = "Dates ate for Hours UT." 

call graphwrits (port, string, 40, 3B, 0, 1, 7) ! itoutina gsnarate^ 

! shadow-like font 
string - "A telescope's view" 
call graphwrice (port, string, 20, 150, 3, 1, 7) 

string - "* ( Tiiae step - 1 hour )" 

call graphwrite (port, string, 40, 164, 3, 1, 7) 

call RectFill (long(port), 512, 0, Slfi, 330] ! Interface to system 
1 RectFillO routine 
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string • "B" 

call graphwrite [port, string, 185, 290, 3, 1, 7) 

string - *S" 

call graphwrite (port, string, 185, 16$, 3, 1, 7) 

String ■ "f 

Ball giiphwrit* [port, string, 360, 230, 3, 1, 1) 

string ■ "H" 

call graphwrite {part, string, 9, 230. 3, 1, ") 

string - "10"! Create color-ceded legend foe Jupiter's Moons 

call graphwrite (post, string, 20; 60, 3, 1, 4) 

call Move Ucng(port), 120, 541 I Hove interfaces to system's Hove (I routine 

call Draw Ucng(port), 160, 54} ! Interface tc system's Drawl) routine 

call Hove Ucng(port), 120, 551 

call Draw Ucng(port), 160, 55} 



string - "EUT0PA" 

call graphwrite (port, string, 20, 75, 3, 1, 5) 

call Hon (long (port), 120, 66) 

call Draw (lcng(port), 160, 68) 

call Mom (long (port), 120, 69) 

call Draw (long (port), 160, 69} 



string - "GAKYKEDE" 

call graphwrite (port, string, 20, 50, 3, 1, 6) 

call Move (long (port), 120, 83} 

call Draw (long (port), 160, 83) 

call Move (long (port), 120, 84) 

call Draw (long (port), 160, 84) 



string • "CAILISTO" 

call graphwrite (port, string, 20, 105, 3, 1, 7) 

call Hove (long (port), 120, 97) 

call Draw (leng (port) , 160, 97) 

call Hove (long (port), 120, 9B) 

call Draw (lcng(port), 160, 98 1 

year - year + 1900 ! Jupiter Moons positioned are computed frcm 1900 

ti»_heut ■ tifle_sinc*jBidnight/3600.0 ! time_since_aidnight is in seconds 

call UTtoET (tin*_hour, EI, year) ! Convert Universal lira to Ephexeris Tiae 

rday - day * ET/24.0 + Tiae_Ione/24.0 ! day in tens of UT with 
! longitude corr. for 

! tin* sone of user. 

call Julian ( year, aonth, rday, JD ) ! Get Julian Day Kusber frrct date and tine 

vrite (Huastr r , '(i2,'/' r i2,'/',i41i'') xanth, day, year ! Convert numbers 

! to string 
string ■ "Local Date: "Y/tfirxstr 
call graphwrite (port, string, 30, 320. 0, 7, 7) 

vrite INumstr," (fl2.2)") JD 

string - "Julian Day Nusber: "//Suaatr 

call graphwrite |port r string, 30, 335, 0, 7, 7) 

writ* (Nuaistr, "" |f 10. 3> "■"> tima^nour 
string - "Tiie (Local): "7/Nuastr 
call graphwrite (port, string, 30, 350, 0, 7, 7} 

JD - aint(JD-ET/24.0! + 0.5 

JD_end * JD + 30 ! Date of end of noons trajectory plot 

JD^begin - JD 

OldX(l) * 0.0; OldXtf] - 0.0; 01dX(3) - 0,0; 01dX(4) - 0.0 

lent - 0; ic.".t_day - 

call Sec RGB (Screen+sc_ViewPort, 8,12,12,12) ! Interface to system's SetRGBO 

call Set KGB (Screen+scJ/iewPort, 1,0,0,0) 

call SetAPen (long (pore J , 7| I Interface to syste&'s SetAPen 

call RectFtll ( lcng(port), 375, ,425, 380 ) 

call SetAPen (lcnglport) , 111 

call RectFill 1 long (pott), 20&, 28, 332, 140) 

call RectFill [ longlport), 25, i«8, 351 r 272) 

call SetAPen (long (port ) ,1) 

call Rectrill ( lcnglport], 27, 170, 349, 270) 

call RectFill ( longlport), 440,0,620,380) 

call RectFill ( long(port), 210, 30, 330, 13B) 

call SetAPen I longlport), 11] 

gall DrawEllipse ( long (port), 268. S3, 2, 2) ! Interface to system's DrawEllipaa 

call SetAPen (long (port) ,3) 

call RaetFill ( longlport). 527, 0, 533. 380> 

call ScToFr (Screen)' ! Bring screen to front - 

! Interface to system's ScreenToFront 

* sac up the text styls 



call CloseFont (font) 
call RenFont (font) 



! Close Times 15 font 
! Renove font fron font list 



t name 



i.-ses.font'V/charlOj 



Set-up Tines 13 font attributes 



f Open disk fant 

! If font not available clean-up exit 



tajfane ■ loc(f_name) 

tl_TSiia - 13 

tj"stylo - FS_BQLD 

tajlags - FP~DISKFOHT 

font - aniga (OpenDiskFont, TextAttr] 

if { font » ) then 
call CloseHindow (Window) 
call CloseScreen (Screen) 
call FreeHea (IaageBlock, size) 
stop "Stop, Times 14 not available." 

endif 



fontl3 • font 

call Hove (long (port), 272, 141) 

call Draw (longlport), 272, 165) 

call SetFont (lone (part), font) 

string - "VIEH ASOVS sguiH POLE' 

call graphwrite (port, string, 1&5, 1S£, 2, 1,9) 

string - 'TO EA&TH' 

call graphwrite (port, string, 235, 165, 0, 14,14) 

- The moons trajectory plots aad inagery shown in adjoining areas of 
windows is generated in the following code - user cannot halt this. 

while ( JD < Jp_ervd ) 

call JMoons (JD, X, X, 1, uc) ! P,outine coKputes Jupiter noons 
f position for current tine. 

call SetAPen |iong{port),3) 

if ( nod|icnt_day,24) - ) then ! Draw lines to nark O & U.T\ 

call SetA?en Hong (port) ,15} 

call Hove (longlport), 440. Ystep) 

call Draw (longlport), ■620- istep) 

call Hove |long{port), 380. Ystep+S) 

call JDtoCAL { JD, rday, nonth, year ) 

call SetAPen |longiport),l2) 

write (Hcautr # '(13,'/*,12,7 f ,t2)"| aonth, int(rday), 
1 year-1900 

call Tex: (longlport), Kunstr, 8) ! Write date string 
endif 

JD - JD *■ 3.041^67 ! Tine step - one hour 

if t Bod(icnti4) • ) then ! Plot trajectory Of the four jsoons 
do (i - I, 4) 

call SetAPen Uong(Window+wd_RPort) ,i+3) 
if ( (abs<OidX(i}} < 1.01 .and, (ue(i) > 0.785) .and, 
1 (uc(i) < 4.712) ) then 
call SetAPen (longlport), 31 

?r,.dif 

call Have acng(Hindow+wd_RPort),530-int(3*01dX(i}}, 
1 OldTstep) 

call Draw Uong (Kindow+vd RPort),530 - int(3*X(i) >,Ystep} 

OldX(i) - X(i} 

OldF(i) - Y(i| 
repeat 

OldYste? - Ystep 
¥/stap - Ystep + 2 
endif 

lent - lent + 1 
icnt_day * icnt^day + 1 

Following code segaent shows the noons of Jupiter for 
given date/tine valuB (JD) as if seen through low-power on 
on telescope. 

call system routine DrawIoage() to re-draw Jupiter icage 

call Drawlnage (longlport), InagePtr, 175, 214) 

Draw noon usages about planet's disk 

do (i - 1, 4} 

if (.not. ||abs|01dXX(i|) < 1.0) .and. (OldZZ(i) > 0.0|| ) 
l then 

call SetAPen (longlport) ,1) 
oldloci » lS5-int(6«01dXX(i)) 
oldiocy - ;2D-int(6'01dr;[i|) 

call RectFill ( longlport], oldlocx, oldiocy, oidlocs*! 
1 ,oidiocy+l) 

endif 

call SetAPen Hong (port) ,lj 
oldlocx « 268 - intl2*01dXX(D) 
oldlocs - A3 - int|2"Old2Z{i)) 

call sect rill Hong (port), oldlocx, oldlocz, oldloqxti, 
1 oldloci+1) 

if ( .not. ll«bs|X|i|) < 1.0) .and. (2(i) > 0.0)) ) then 

call SctnPon [long [pert) , i-*-3> 
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locx - lB5-int|6'Xli)l 

iocy ■ 220-int(6*Y(i)) 

call rlectrill (long (port), locx, lacy, locx+1, locy+1) 
endif 

OldXXdl - X(il 
QldYY(U - I[U 
OldZZli) - Z(U 
call SetAPen (long(port),i+3) 
loci - 268 - int(2-Xti)> 
loci - B3 - int(2'Z{i)) 

call RectFill {long (port), locx, loci, locx+1, locz*l) 
repeat 

repeat 

After moons trajectories ate plotted, the window's gadget list 
is assigned to window by calling system's AddGListd and aade 
viewable by calling system's RefreshGadgets () 

gad_j=05itio^ - AddGList (Window, loc(Gadget Quitl, 3, -1, 0) 

call ariga (RefreshGadgets, loc(Gadgetj2uit) , Window, 0) 

call SetAPen (lsngipcrt), Q) 

call RactFill (long'lport), 30, 152, 175, 166) 

string - " ( Time step - 0.1 hour I* 

call graphwrite (port, siting, 40, 161, 3, 1, 7) 

oldstring = string 

The following line of cods disables the STOP gadget 

call OffGadgat ( loclGadget_Stop), Window, 0) 

the following code segment allows for and responds to user inputs 
as defined by the gadgets user actions. 

Waiton = .TRUE. 

du while (Walton) 
message - GetMsg (longlWinic-w+wdJJserPort)) '. IDCH3 message available 
ii (-ess age - )J then ! No massage, go to sleep, 

iteisp - byteUcng<tfindovtwd_UseiFoiE] * MF_SIGSIT| 
result - shift {one, it cap) 
call Wait (result) 
else 

class - lQng(message+ia_Classl ! There is a aeasage, gat class 
code ■ wcrd (message + im_Code) ! get code 

GadgePtr ■ lotiglrtessage + iffiJAddress)! Get GadgePtr 
Gadget-IE ■ word(GadgePtr + 38) ! Get program defined ID 
call ReplyMsg (message) ! Tell system we got nessage 

if (class - CLO5EHIHD0M) then ! It true cloa* window gadget, selected 

Waiton • .FALSE. I exit from while loop 

z:.± ::' 

! User defined gadget selected? 
! Yes, is it fron noon traj. plot? 
Yes, get moiise click position 



if (class - GAKSTDCWK) then 
if ( GadgetID - 1 ) then 
res - vord(Wimdctf-+wd_KcuseX) 
By - wcrd(Kindow+wd_MouseY) 
JD - JDj?egin + (ay-16| /12.0 

call Haftefics (port, ImagePtr, 
OldYY, 



! Resolve from position the date and tiM 
JD, X, Y, Z, OldXX, 
Qld£t) ! Make new pictures reflecting corresponding 
! moon positions for date and tuna 
call OffGadget ( lQc|Gsdget_Stopl, Window, 01 ! Enable and disable gadgets 
call OnGadgst ( loclG3dget_R»windl , Window, Q> 
call OnGadget ( loclGadget~5tart), window, 0) 

else if { GadgetID - ~ti )~then ! 
Waiton - .FALSE, 
else if [ GadgetID - 2 ) then 1 
then 



User selected quit gadget? 
User selected Rewind to h. UT 



if ( (JD - aint(JD)) > 0.5 \ 

JD - aint(JD) + 0.5 
else 

JD - aint(JD) - 0.5 
endif 
call KakeFics (port, ImagePtr, JD, X, Y, Z, OldXX, 

OldYY, QldZZI ! Make new pictures for h of given date 

else if ( GadgetID - 4 > then ! User selected Start gadget; 
call OnGadget ( loc(Gadget_£top| , window, 0) 
call Off Gadget ( loc(Gadget_Rewind), Window, 0) 
call OffGadget f loc|Gadget_Start) , Window, 0) 

shaw neons positions over 2A hour period starting within 
date resolved from trajectory plot. Time step '0.1 hours. 

do ( i - 1, 240 ) 

call HakePics (port, ImagePtr, JD, X, ¥, I, OldXX, 

OldYY, OldZZ) 
cessage - GetHsg (longtKir.dow-iwdJJseiPort) ) 
if { message <> ) then ! User has selected a gadget 

call OnGadget ( lec (Gadgat_Rewind) .Window, 0) 

call OnGadget i ioc{Gadget_5tart) ,Wir,dcw,Cj 

caii OffGadget ! loc (Gadgat_Stcp) .Window, G) 

class *> long |me5sage*in_Class> 

code - word (nessage » ua_Code) 

GadgePtr - long (nessage * iK_!Address) 

GadgetID - word (GadgePtr ♦ 36) 

call ReplyMsg (nesaagH 

if (class - GADGETOOWSI then ! User Selected STO? gadget! 



if I GadgetID - 3 ) exit ! if so exit do-loop 

endif 
rr.;:: 

JD - JD • 0.00416667 ! increment by an 1/10 of hour 
enddo 

call Cr.Sadget 1 liclGaiger^Sewir.d) ,W:-d:w,jj f Enable and disable gadgets 
call OnGadget ( loc(Gadget_Start) .window, 0) 
call OffGadget I loo (Gadget_Stop) .Window, 0) 
endif 
endif 
endif 
repeat 

Ke get here if user selects either QUIT gadget or window's clos» gadget 

call CioseKindev (Window) 

call CloseScreen (Screen) 

call TreeHem (IiageBlock, siie) 

call rree-He?. (iT^geBackGr, siiel) 

call CloseFont {font) 

call Percent (font) 
- Fores all the Tines fonts opened by program of system fonts list 
nostly for Version 1.32 of the Amiga OS 

call Rearont (iontl3) 

call ReraFont (fontH) 
call RemFont (font25) 

stop 

end 

following subroutine is used to draw Jupiter and noons configurations 

picture?, 

Subroutine naileries (port, Iir.agePtr, JD, X, Y, l, Olaxx, 
+ OldYY, OldlZ) 

i.-.j licit nans! Again force js to dzz*. typ4 all variables 

real*S JT 

ieal*4 rday, temp 

integer*^ month, year, oldlocx, o Idiocy, locx, lecy, ImagePtr 

iatmgw*4 loci, oldlcci, i, port 

realM ucii), OldXX(^), 01dYY(4), 01dZZ(4), X(4), Y(l), 2(4) 

character*20 cldstring, stringi 

the following save is done to preserve varies till next call to this routine 

save oldstring, string 

call JDtoCAL ( JD, rday, ncnth, year ) 

call graphwrite (port, cld=tring, 30, 260, 0, 1.11 

write (oxdstrmg ( ' , (i2,'/',i2,V\i2)"l aonth,int (rday) , 
1 year-lSOO 

call gr«Fhwrlte IpO^t, oldstring, 30, 2fi0, 0, 10,10) 

Canp - (rday - int (tdayl | "i4.0 

call graphwrite (port, string, 80, 260, 0, 1,1) 

write (string, "(F6, 2} ') tenp 

string - ' Tine (UI) : V/string 

call graplvrite (port, string, 80, 260, 0, 10,10) 

call JMoons (JD t X, Y, Z f tic) 

call Drawlmage (long (port), ImagePtr, 119, 214) 

do <i - 1, 4) 
if ( .not. ((abs (OldXX (D) < 1.0) .and. 
* (01d:S(il > 0.011 1 then 
call SetAPen (long(pott),l) 

oldlocx - LB&-jjit io'OldXXliM 

oldlocy - 220-int(6'OldyY(i)) 

call RectTlllI long (port J , oldlocx, oldlocy, oldloci+1 

1 ,aldlocy+l) 
endif 
call SetAFen (long (part) ,1) 
oldlocx - 268 - int|2"01dXX(i)) 
c-ldlocr - 83 - int(2*01dZZli)l 
call RectFill (long (port), oldlocx, oldlocz, oidlocx+1, 

1 oldloot+1) 

if ( ,not.l(abs(X(i)) < 1.0) .and. (Z(i) > 0.D))) 

+ then 

call SetAPen {long (port), i+3) 

locx - lfl5-int{6*X{i1| 

locy - 220-int{6*Y<i|| 

call KactPill (long [port! , locx, locy, locx+1, locy* 1) 
endif 

OldXX {i} - X(i) 
OldYY li) - Y(i) 
OldZZ (i) - S(i) 
call SetA?e.i (long (port), i+3) 
locx - 268 - int(2»X(i)) 
loci - B3 - iBt{2»I{i)J 

call RectFill ( long (port ) does., loci, locx+1 ,loci+i} 
enddo 

return 
end 
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Toolbox- 
Amiga Programming Solutions 

An Introduction to 3-D Progromming 

by Patrick Quaid 



Raisin Debt 

Suppose you're writing a program that, say, organizes your 
soupcans. You've got your Intuition interface, your file requesters, 
your ARexx commands, but what you don't have is a routine to 
alphabetically sort the cans. So what do you do, sit down and 
write one from scratch? You could — it's not all that hard. For all 
I know, you might write the greatest sort algorithm known to 
mankind. On the other hand, hundreds of programmers have 
spent decades developing and refining sort routines fo the point 
thatany further improvement, while possible, is bloody unlikely. 
Put more positively, your efforts would be more profitably spent 
directed toward other areas of your program. 

This idea is often summarized by the aphorism "Why re- 
invent the wheel?" The answer, of course, is that if no one had 
done so, they'd still be made of stone. So although you are 
unlikely to come up with a better sort routine, other algorithms 
are much closer to the stone wheel stage, and, of course, the 
majority fall somewhere in between. 

The point of all this is that you should spend your time 
creating new stuff, rather than recreating old stuff. Fine, but in 
order to do that you need to know the old stuff. Well, that's where 
this column comes in. In each issue, we'll go over a different area 
of programming, looking at someexisting solutions and discuss- 
ing their pros and cons. In this first column, for example, we take 
a look at 3-D drawing techniques. Later we'll goover multitasking 
— how to do it, when to do it, what to wear. We'll investigate 
random numbers and graph traversals, and maybe even discuss 
some of those finely-tuned sort routines. 

Since few problems have one "best" solution, we'll normally 
look at several different approaches. Each algorithm will be 
illustrated by a complete, working example program. These 
examples will be written specifically for the Amiga, but in many 
cases the underlying ideas apply to computers in general. The 
programs will be written in C, Modula-2, Assembly, ARexx — 
whatever language best suits the job at hand. 



The goal of the examples, and the column as a whole, is to 
give you ideas, algorithms, and even complete subroutines that 
you can include in your code. I hope they'll provide a map 
through the known, so you can begin blazing trails through the 
unknown. 

Perspective and Depth 

The world of computer graphics ranges from simple wire- 
frame outlines to full photo-realistic rendering. This article will 
cover the entire spectrum in excruciating detail. Hey — just 
kidding — but we will introduce the wire-frame part, and later 
we'll expand to a flexible, filled-surface drawing system. 

But first some fundamentals. The equations governing per- 
spective graphics are easily derived from high school geometry 
and a passing familiarity with photography. Take a look at the 
"pinhole camera" model shown in Figure 1. You can see that we 
have an object to look at (a palm tree, in this case), the camera's 
pinhole or focal point (labelled F), and the two dimensional 
image, which inourcase will be the screen. Friendly little photons 
shoot from the top of the tree, through the pinhole, to leave their 
marks on the bottom of the screen. 

The image on the screen ends up upside down, but that's no 
big deal — we could, after all, just define our objects backward. 
Instead we'll get rid of the problem by flipping the screen to the 
same side of F as the object, as shown in Figure 2. This setup more 
clearly shows the derivations of the equations we'll need. 

That queasy feeling in your stomach signals geometry, dead 
ahead. First of all, let's define what we want out of all this, to wit: 
given a point P specified by the 3-D coordinates (x, y, z), where on 
the screen show we draw its image P'? Consider the right triangle 
formed by the points F, A, and P. Done? OK, now look at the 
triangle formed by the points F, C, and P'. Prove that these 
triangles are similar (answer: they look a lot alike, QED). Since 
they are in fact similar, the ratio of y' to y is the same as that of d 
toz. Algebraically that looks like y'/y = d/z, which when solved 
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Figure One 

The Basic 
Pin-hole 
Camera 
Model 



for y' becomes: y' = yd/z. We're not quite done, because we 
actually wanted the position of P'. To get that, we take what we 
just got and add it to the y component of C, the center point of the 
screen. You can relax — the derivations are over for now. 

If you tilt your head to the side and read the previous 
paragraph again, you'll see that you can use the same equations 
to figure out the x component of P'. Thus for any point in space, 
the associated screen position is given as follows: 

|x',y'l - (Cx + xd/z, Cy + yd/zl 

The constant d in this equation defines the distance between 
the foca! point F and the screen. In Figure 2 you can see that the 
angle v, the field of view, can be defined in terms of d, and vice 
versa. Small values for d result in fish-bowl effects, like a wide- 
angle camera lens, while larger values tend to flatten out distances 
like a telephoto lens. 

Since straight lines in space become straight lines on the 
screen, perspective drawing reduces to converting 3-D points in 
space to 2-D screen coordinates, then drawing lines between all 
the endpoints. It's all so incredibly simple. 

Well, maybe not. For one thing, we have to be sure z doesn't 
stray too close to zero or the x' and y' values will blow up. When 
z is negative, we have another embarrassing problem: the points 
still show up on the screen, turned inside out. That's all easy 
enough to handle, I guess. The real problem is the load of 
limitations this scheme imposes — it makes you stick your 
camera on a tripod and won't let you move it. But we're dynamic, 
'90's sort of people, so we don't like limitations. We want to be 
able to move the camera anywhere, point it at anything, and tilt 
it to any fashionable angle. We want to set the focal length of lens, 
and we want to take pictures of gorgeous babes. I can handle all 
but one of those — if you can help on the other, let me know. In 
any case, we won't address these issues until next time. 




For this column we'll work within our limits to develop a 
very simple set of graphic display routines. We'll open a window, 
define some default values, and draw... what? Well, to add some 
measure of flexibility to this first program, we'll read an object 
definition from a text file. Lef s take a deeper look at it. 

First of all, why a text file? It's going to be much bigger and 
slower than an equivalent binary file, but it has two important 
advantages. For one thing, it's easy to see what's going on, which 
is the point of this article after all, and for another you won't need 
a special program just to create the data file. If we were going to 
develop a commercial program, we would of course invent our 
own proprietary, encoded, impossible-to-modify file format in 
order to feel like professionals. 

Example object descriptions are offered in Listing #2 (en- 
titled "Two Boxes") and Listing #3 ("Self Portrait"). The first line 
is a constant z offset, which will be added to each of the points in 
the object. This allows us to define data points around the origin, 
which I find easiest, then push them all far enough away to see. 




Figure Two The Model Used to Derive Our Equations 
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Listing Two 




Two Boxes 




80 






22 






70 


100 


-30 


110 


100 


-20 


120 


90 


-10 


30 


100 


-30 


-10 


100 


-20 


-20 


90 


-10 


50 


95 


-30 


50 


20 


-60 


30 


30 


-30 


70 


30 


-30 


10 


-40 


-10 


25 


-50 


-20 


75 


-50 


-20 


90 


-40 


-10 


80 


-100 





20 


-100 





-30 


-50 





-30 


150 





20 


200 





80 


200 





130 


150 





130 


-50 





18 






1 






1 2 






3 4 






4 5 






6 7 






7 8 






7 9 






10 11 






11 12 






12 13 






14 15 






15 16 






16 17 






17 18 






18 19 






19 20 






20 21 






21 14 







Listing Three 


Self Portrait 




200 




16 




-100 -100 


-100 


100 -100 


-100 


100 100 


-100 


-100 100 


-100 


-100 -100 


100 


100 -100 


100 


100 100 


100 


-100 100 


1Q0 


-400 -400 


-100 


-200 -400 


-100 


-200 -200 


-100 


-400 -200 


-100 


-400 -400 


100 


-200 -400 


100 


-200 -200 


100 


-400 -200 


100 


24 




1 




1 2 




2 3 




3 




4 5 




5 6 




6 7 




7 4 




4 




1 5 




2 6 




3 7 




8 9 




9 10 




10 11 




11 8 




12 13 




13 14 




14 15 




15 12 




B 12 




9 13 




10 14 




11 15 





We could equivalently add theoffset to each individual point, but 
keeping it separate makes it easy to change. The second line holds 
the total numberof data points. Following that a re the data points 
themselves, one to a line, specified as the triple x, y, and z. After 
all that, we get the total number of lines that we will define. The 



rest of the file consists of these line definitions, each of which 
refers to its endpoints using the order in which the points were 
read (e.g., the first data point is point 0). Why define the lines 
separately? It's not terribly important in this example, but in 
future articles each data point will typically participate in several 
lines, so using this method cuts down on the number of points we 
need to calculate. 

We read these values into a few arrays, which for now are of 
fixed size. Then we convert the 3-D points to 2-D screen posi tions, 
a II at once, a nd use those v a I ues a long wi th the connec tivi ty array 
to draw a bunch of lines on the screen. To flaunt our mastery of 
special effects, we'll simulate actual motion by erasing the image 
and redrawing it slightly farther away. You won't believe your 
eyes. To keep the image from flickering too badly, I've used a 
naive method of double-buffering. It simply uses two screens, 
drawing on the hidden one, then flipping it to the front. Not user- 
friendly, but effective. 

The program itself is written in C, and compiles with DICE 
or Sozobon C. You can get by without the standard Amiga 
include files if you define NewWindow and NewScreen directly, 
but in the future we will increasingly rely on the includes and the 
standard library, so it would be a good idea to send away for 
them. In addition to the C headers you get assembly includes, 
documentation for the library functions, and all sorts of other fun 
stuff. To get all this, send $20 to CATS (Commodore Application 
and Technical Support) and ask for the AmigaDOS 1.3 Native 
Developers Update (at this writing, the AmigaDOS 2.0 update is 
not yet available). The address for CATS is: 

CATS 

1200 Wilson Drive 
West Chester, PA 19380 

The system we've created this time works fine, and if you can 
arrange your data points to suit this method, you're all set. 
Nonetheless, it certainly has its problems. For one thing, we use 
normal integers to specify points. This leaves us open to round- 
off errors, so we're going to need to use fractional numbers 
somehow. Plus we have the constraints of the model to deal with: 
the camera is always fixed at the origin, pointing along the 
positive z axis. The positive y axis always points up. Next time 
around, we'll overcome all of these problems. Heck, we'll invent 
extra problems, just to overcome them. The price, as usual, will be 
additional calculations. 
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Listing One 

3D.c 



/* 



3D.c 

This program reads an object specified in 
3-dimensional coordinates and displays it 
using perspective rendering. 

Usage: 3d InputFile 



Hnclude <stdio.h> 

^include "intuit ion/ intuit ion . h" 

/* Maximum number of data points we can read. 

/* We'll also use this to determine the max 

/* number of line segments, which we'll set 

/* arbitrarily at MAXP0INTS*2 



♦define MAXPOINTS 



30 



/* This is the distance between the focal 

/* point and the screen. A small value here 

/* creates fish-bowl pictures. Larger values 

/* minimize the effects of perspective. 

/* Dse a power of two here if possible - that 

/* way the compiler will convert the 

/* multiplication below to a much faster shift 



*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 



♦define DISTANCE 



32 



/* Define constants for our screen size. If you */ 

/* set MAXX to 640 or MAXY to 400, the screen */ 

/* automatically be opened in HIRES and LACE */ 

/* modes (see OpenDisplay ) */ 



♦define MAXX 

♦define MAXY 

♦define HALFX 

♦define HALFY 



320 
200 

(MAXX / 2) 
(MAXY / 2) 



/* 3D_Point : One point from the input file. 



typedef struct ( 

long X, Y, Z; 
} Point_3D; 



/* 2D_Point : The screen image of a 3D_Point 

typedef struct ( 

long X,Y; 
( Point 2D; 



/* LineSeg : One line segment from input file 

typedef struct ( 

long start, end; 
I LineSeg; 



/* The libraries we'll need: 



void *IntuitionBase — 0/ 
*Gf xBase — 0; 

/* To get rid of flicker, we'll actually open two */ 

/* screens, then flip back and forth to simulate */ 

/* double buffering. This is an easy, but user— */ 

/* unfriendly method. To boo why, try doing */ 

/* anything else while this demo is running. */ 

struct Window *windowl = 0, 
*window2 — 0, 
* f rontwindow; 

struct Screen *screenl ■- 0, 
*screen2 =0; 



/* Regardless of which screen is in front, this */ 

/* rastport will always be the correct one in */ 

/* which to draw. */ 

Struct RastPort *rp; 



/* Our input file: */ 
FILE "ObjectFile = 0; 

/* Tha massage that will tell us to get out: */ 

struct Message *quitmsg; 

long z^offset, /* Current offset */ 

initial_of fset; /* From the input file */ 

long TotalPoints, /* Number of data points */ 

/* from input file */ 

TotalLines; /* Number of line segments */ 

/* defined in input file */ 

/* Actual object data read from the input file */ 
Point_3D Points [MAXPOINTS] ; 

/* 3D points converted to screen coordinates */ 
Point_2D Display [MAXPOINTS ]; 

/* Line segment definitions from input file */ 
LineSeg Lines [MAXP0INTS*2] ; 



/* If for some reason we can't open a screen or */ 
/* something else goes haywire, we call this */ 
/* routine to notify the user and bug out cleanly */ 

void Quit (msg) 



char 



*msg; 



if (ObjectFile) 

f close (Ob jectFile) ; 

if (windowl) 
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CloseWindow(windowl) ; 
if (screenl) 

CloseScreen (screenl) ; 

if (window2) 

CloseWindow (window2) ; 
if (screen2) 

CloseScreen (screen2) ; 

if (IntuitionBase) 

CloseLibrary ( IntuitionBase) ; 
if (GfxBase) 

CloseLibrary (GfxBase) ; 

puts (msg) ; 
exit ( ) ; 



/* This routine is fairly straightforward. It */ 
/* reads the data from the file, expecting integer*/ 
/* numbers in the following order: */ 



Initial_Z_Offset 
Number_Of_Data_Points 
Data_X Data_Y Data_Z 

Number_Qf_Line_Segments 
Start Point End Point 



*/ 
*/ 
*/ 
*/ 

'•' 
*/ 



/* Note that by cleverly using standard C IO */ 
/* routines, we have allowed ourselves the freedom*/ 
/* to insert as much or as little white space as */ 
/* we like between the numbers. Therefore the */ 
/* order of the values is important, but the */ 
/* layout is up to you. */ 

void ReadOb jectFile ( fname) 

char * fname; 

i 

char *ErrorMsg «* 

"Error reading object definition"; 
long Coord; 
short Seg, i; 

Ob jectFile = fopen (fname, "r") ; 
if (ObjectFile) ( 

if (fscanf (ObjectFile, "%ld", 
Sinitial_of fset) ==EOF) 

Quit (ErrorMsg) ; 

if (fscanf (ObjectFile, "%ld", iTotalPoints)— -EOF) 
Quit (ErrorMsg) ; 

if ( (TotalPoints<l) I ! (TotalPoints > MAXPOINTS) ) 
Quit ("Point count out of range"! ; 



for (i-0; KTotalPoints,- i++) 

if (fscanf (Ob jectFile, "%ld %ld %ld", 
SPoints [i] .X, SPoints [i] . Y, SPoints [i] . Z) — EOF) 
Quit (ErrorMsg) ; 

if (fscanf (ObjectFile, "%ld", sTotalLines)— EOF) 
Quit (ErrorMsg) ; 

if ( (TotalLines<l) I I (TotalLines > MAXP0INTS*2) ) 



Quit ("Line count out of range"); 

for (i-0; KTotalLines; i++) 

if (fscanf (ObjectFile, "%ld %ld", 

SLinesli] .start, SLinesfi] ,end)~EOF) 
Quit (ErrorMsg) ; 

fclose (ObjectFile) ; 
} else 

Quit ("Could not open input file") ; 



/* Open a couple of screens and windows. We'll */ 

/* need two of each for double buffering. Also, */ 

/* this routine jump-starts the double buffering */ 

/* process. */ 

void OpenDisplay ( ) 
( 

struct NewWindow NW; 

struct NewScreen NS; 



NS.LeftEdge 


= 


0; 




NS . TopEdge 


- 


0; 




NS. Width 


- 


MAXX; 




NS. Height 


- 


MAXY; 




NS .Depth 


- 


1; 




NS.DetailPen 


■ 


0; 




NS.BlockPen 


- 


0; 




NS . ViewModes 


= 


( (MAXX > 320) ? HIRES 


: 0) 






( (MAXY > 200) 7 LACE 


: 0) 


NS . Type 


- 


CUSTOMSCREEN; 




NS.Font 


- 


NULL; 




ns .DefaultTitle 


- 


(UBYTE *) "",- 




NS. Gadgets 


- 


NULL; 





if (! (screenl - (void *) OpenScreen (6NS) > ) 

Quit ("Could not open screen") ,- 
ShowTitle (screenl, FALSE); 

if (!(screen2 - (void *) OpenScreen (SNS) ) ) 

Quit ("Could not open screen"); 
ShowTitle (screen2, FALSE); 



NW.LeftEdge 


= 


0; 


NW. TopEdge 


= 


0; 


NW. Width 


- 


MAXX; 


NW. Height 


- 


MAXY; 


NW.DetailPen 


- 


0; 


NW.BlockPen 


= 


0; 


NW.IDCMPFlags 


■ 


VANILLAKEY; 


NW. Flags 


- 


BACKDROP I BORDERLESS | ACTIVATE; 


NW.FirstGadget 


- 


NULL; 


NW.CheekMark 


- 


NULL; 


NW. Title 


= 


(UBYTE *) ""; 


NW. Screen 


= 


screenl; 


NW.Type 


= 


CUSTOMSCREEN; 



if (! (windowl — (struct Window *) OpenWindow (SNW) ) ) 
Quit ("Could not open the window") ; 



NW. Screen 
NW.IDCMPFlags 
NW, Flags 



- screen2; 

- 0; 

- BACKDROP I BORDERLESS, - 



if 



( ! (window2 - (struct Window *) OpenWindow (SNW) ) ) 
Quit ("Could not open the window"),- 
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frontwindow - windowl; 
ScreenToFront (screenl) ; 

rp *= window2->RPort ; 



/* Shows the screen we have, presumably, just */ 

/* finished drawing on. This routine also sets */ 

/* up the correct rastport, so if we always draw */ 

/* into rp we never need to know the details of */ 

/* which screen is in front. */ 

void SwapBuf f ers ( ) 
( 



rr 



f rontwindow->RPcrt ,- 



if (frontwindow »- windowl) ( 
ScreenToFront (screen2) ; 
frontwindow - window2; 

) else ( 

ScreenToFront (screenl) ,- 
frontwindow - windowl ; 



Given the 3D coordinates, calculate the screen 
position. Note that we actually switch the Y 
screen coordinate to go from bottom to top, to 
match our model. Also note that we avoid 
division by zero problems, but I left in the 
negative Z problem so you could see what it 
looked like. Normally you'd just refuse to 
draw any point behind the camera. 



*/ 
*/ 

*/ 

*/ 
*/ 
*/ 
*/ 
*/ 



void CalculateDisplay () 
{ 

long i, ActualZ; 

for (i-0; i<TotalPoints; i++) ( 

ActualZ - z_offset + Points [i] . Z; 
if (! ActualE) 

ActualZ - 1; 

Display [i] -X « 

(Points [iJ.X * DISTANCE) / ActualZ + HALFX; 
Display [i] .Y - 

HALFY - (Points(i).Y » DISTANCE) / ActualZ; 



/* Having figured out all the correct screen 
/* positions, display the object in the given 
/* color. 

void ShowObject (color) 

int color; 



*/ 
*/ 

*/ 



1 



short i ; 

long startpoint, endpoint; 

5etAPen{rp, color); 



MISSED AN ISSUE? 

CHANGE 

OF ADDRESS? 

SUBSCRIPTION 
PROBLEMS? 



CALL US! 

1 -800-345-3360 






for (i-0; KTotalLines; i++) ( 
startpoint = Lines [i] .start ; 
endpoint ■= Lines [i] . end; 

Move(rp, Display [startpoint] .X, 
Display [startpoint] .Y) 



Draw (rp, 



Display [endpoint] .X, 
Display [endpoint] .Y) ,- 



In the main routine, we initialize all the 
globals, as well as open the screen and read 
the object from the input file. We then 
begin displaying the object, varying the z 
offset as we go to simulate motion. If we 
wanted to get tricky we could do similar 
things to the x and y axes, too. 



main(argc, argv) 

int argc; 
char *argv [ ] ; 



long increment ; 
if (argc < 2) 
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Quit ("Usage: 3d objectfile") ; 

if ( ! (IntuitionBase — (void *) 

OpenLibrary ("intuition. library", OL) ) ) 
Quit ("No Intuition") ; 

if (! (GfxBase - (void *) 

OpenLibrary ("graphics .library", OL) ) ) 
Quit ("No Graphics"); 

OpenDisplay () ; 

ReadOb jectFile (argv[l] ) ; 

z_offset = initial_of fset; 

increment ■ (initial_of f set / 100) + 1; 

CalculateDisplay () ; 

while ( ! (quitmsg — 

(void *) GetMsg(windowl->UserPort) ) ) ( 

for (z_offset = initial_of fset; 

z_offset < (initial_offset « 2) ; 
z_offset +- increment) ( 

CalculateDisplay () ; 

SetAPen Irp, 0) ; 

RectFilKrp, 0, 0, MAXX, MAXY) ; 

ShowObject (1) ; 

SwapBuf fers ; 



for (z_offset - (initial_of fset « 2) ; 
z_offset > initial_of f set ; 
z = offset -™ increment) ( 



CalculateDisplay!) ; 
SetAPen (rp, 0) ,- 
RectFilKrp, 0, 0, MAXX, 
ShowObject (1) ; 
SwapBuf fers ( ) ; 



ReplyMsg (quitmsg) ; 

CloseWindow (windowl ) ; 
CloseScreen (screenl) ; 
CloseWindow (window2) ; 
CloseScreen (screen2) ; 

CloseLibrary (IntuitionBase) , 
CloseLibrary (GfxBase) ; 



MAXY) ; 



WE INTERRUPT THIS HIGHLY INFORMATIVE ARTICLE 
FOR A VERY SPECIAL PROGRAM ANNOUNCEMENT! 

We want to publish your very special program in an upcoming issue of AC. 

Or, your highly informative article on any topic of interest to Amiga users of all skill levels! 

The fact is, Amazing Computing has always published the most unique, most detailed Amiga 
programming articles and tutorials found anywhere! AC pays competitive per-page rates to 
its authors, fjut publishes more and longer programming articles per issue than any other 
Amiaa monthly. That's great news not only for our readers, but also for those of you who 
are thinking about achieving fame and fortune as freelance writers! And now, the more 
complex works of high-level programmers are considered for publication in AG's TECH. 
The fact is, AC's TE&H is the #1 all-technical, disk-based Amiga journal. 

Whatever your areas of greatest interest or proficiency on the Amiga, there are probably any 
number of tips, techniques and tricks you can communicate to Arnica users wor dwide, in 
the pages of Amazing Computing. 

Even if you have never been published before, you should consider writing for AC. Our 
knowledgeable, experienced editors are the most helpful in the business. 

Call our editorial offices during normal business hours at 1-800-345-3360 to have 
the Amazing Computing Author's Guide information packet sent to you TODAY! 
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Bars&Pipes", by Ben Means 

"Microillusions' Music-X", review by Rob Bryanton 

"MusicTiller", Generating a tiller display to accompany the 

audio on a VCR recording, by Brian Zupke 
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V Vol. 5 No. 4, April 1990 
Highlights include: 

"Handling MS-DOS Flies", Adapting your Amiga to MS- 
DOS using a 5.25" disk drive, by Jim Locker 
"Bridging the 3.5" Chasm", Making Amiga 3.5' drives 
compatible with IBM 3.5" drives, by Karl D. Belsom 
"Bridgeboard Q £c A", by Marion Deland 
"Handling Gadget & Mouse InlulEvents", More gadgets in 
Assembly, by Jeff Clatt 

"Ham Bones", Programming in HAM mode in AmigaBASIC, 
by Robert D'Asto 

"Gambling with your video, Amiga-style", Problems with 
trading genlocks with your friends, by Oran Sands 

*' Vol. 5 No. 5 May 1990 

Highlights include: 

"Commodore's Amiga 3000", preview 

"Newtek's video Toaster", preview 

"Do It By Remote", Building an Amiga-operated remote 

controller for your home, by Andre Theberge 

"Turn Your Amiga 1000 Into A ROM-based Machine", by 

George Gibeau Jr. & D wight Blubaugh 

"Super Bitmaps In BASIC", Holdings graphics display larger 

than the monitor screen, by Jason Cahill 

"Rounding Off Your Numbers", by Sedgewick Simons Jr. 

"Faster BASIC Mouse 1 nput", by Michael S. Fahrion 

"Print Utility", by Brian Zupke 

V Vol. 5 No. 6, June 1990 
Highlights include: 

"Convergence", Tart 5 of the Fractal series, by P. Caslonguay 

"C++: An introduction to object-oriented Amiga 

programming", by Scolt B. Sleinman 

"APL and The Amiga: Primitive Functions and Their 

Execution", by Henry T. Lippert 

"Amiga Turtle Graphics", by Dylan McNamee 

"Building A Rapid Fire Joystick", by John [ovine 

The AM 512", Upgrade your A50Q to a 1 megabyte machine, 

by James Bentley 

1* Vol. 5 No. 7, July 1990 

Highlights Include: 

"Commodore Announces CDTV" 

"Apples, Oranges, and MIPS: 6S03O-based Accelerators For 

The Amiga 2000", by Ernest P. Viveiros, Jr. 

"Exceptional Conduct", Quick response lo user requests, 

through efficient program logic, by Mark Cashman 

"Poor Man's Spreadsheet", A simple spreadsheet program 

that demonstrates manipulating arrays, by Gerry L. Penrose 

"Tree Traversal and Tree Search", Two methods for 

traversing trees, by Forest W. Arnold 

"Cruitchy Frog II", by Jim Fiore 

"Getting to the Point: Custom Intuition Pointers In 

Am igaB AS IC", by Robert D'Asto 

"Synchronic! ty; Right & Left Brain Lateralization", by John 

lovine 

"Snap, Crackle, ft POP!", Fixing a monitor bug on 

Commodore monitors, by Richard Landry 

»" Vol.5 No. S.August 1990 

Highlights include: 

"Mime-tics' FrameBuffer", review by Lonnie Watson 

"The VidTeeh Scanlock", review by Oran Sands 

"Amigas in Television", The Amiga in a cable television 

operation, by Frank McMahon 

"Desktop Video in a University Setting", The Amiga at work 

at North Dakota State University, by John Steiner 

"Credit Teal Scroller", review by Frank McMahon 

"Graphic Suggestions", Other ways lo use your Amiga in 

video production, by Bill Burkell 

"Title Screens That Shine: Adding light sources with 

DeluxePaint 111", by Frank McMahon 

The Amiga gues to the Andys", by Curt Kass 

"Breaking the RAM Barrier", Longer, faster, smoother 

animations with only one meg of RAM, by Frank McMahon 

"Fully Utilizing the 6B881 Math Coprocessor Timings and 

Turbo_Pixel functions", by Read Predmore 

"APL and the Amiga: Part IV", by Henry T. Lippert 

"Sound Quest's MldlQuest", review by Hal Bclden 

¥ Vol. 5 No. 9, September 1990 

Highlights include: 

"Dr. T's Keyboard Controlled Sequencer 3.0", review Phil 

Saunders 

"Acting On Impulse", A visit to Impulse, by John Steiner 

"3-D Professional", review by David Duberman 

"Programming In C on a Floppy System", Yes even a stock 

A500 with a 512K RAM expander, by Paul Miller 

"Time Out", Accessing the Amiga's system timer device via 

Modula-2, by Mark Cashman 

"Stock Portfolio", An original program to organize your 

investment, music library, mailing lists, etc, by G.L. Penrose 



"Voice-Controlled Joystick", by John lovine 

"FrameGrabber", review by Lonnie Watson 

"Gradient Color Dithering on the Amiga Made Easy", by 

Francis Gardino 

"Sculpt Scripl", by Christian Aubert 

"The Art Department", review by R. Shamms Mortier 

"Breaking the Color Limit with PageRender3D", review by R. 

Shamms Mortier 

¥ VoS. 5 No. 10, October 1990 

Highlights include: 

"Notes on PostScript Printing with Dr. Ts Copyist", by Hal 

Beldcn 

"BioMetal", Make the Amiga flex its first electric muscle, by 

john lovine 

"Atlanta 1996", Will Atlanta host the 19% Summer Olympics? 

Their best salesperson is an Amiga 2500. 

"CAD Overview: X-CAD Designer, X-CAD Professional, 

IntroCAD Plus, Aegis Draw 2000, Ultra Design", by Douglas 

Dullard 

"Saxon Publisher", review by David Duberman 

"Auto Prompt", review by Frank McMahon 

"Sound Tools for the Amiga", Sunrize Industries' Perfect 

Sound and MichTron's Masler Sound, reviews by M. Kevelson 

"Stripping Layers Off Workbench", Remove unneeded files 

on your Workbench to make room for other programs, by Keith 

Cameron 

"Audio Illusion", Produce fascinating auditory illusions on 

your Amiga, by Craig Zupke 

"Call Assembly Language From Modula-2", Integrating 

small, fast machine language programs into BASIC, by Martin 

Combs 

"Koch Hakes", Using the preprocessor to perform selective 

compilation, by Paul Caslonguay 

"C Notes from the C Group", A program that examines an 

archive file and removes any files that have been extracted, by 

Stephen Kemp 

¥ Vol. 5 No. 11, November 1990 

Highlights include: 

"Getting A Lol For A Little", A comparison of the available 

Amiga archive programs, by Greg Epley 

"Amiga Vision", review by John Sleiner 

"High Density Media Comes to the Amiga", Applied 

Engineering's AEHD drive, review by John Steiner 

"Fixing. The Flicker", MicroWay's Advanced Graphics Adaptor 

2000, by John Sleiner 

"The KCS Power PC Board", If you have an Amiga 500, and 

need IBM PC/XT software compatibility, the KCS Power PC 

Board can help, by Ernest P. Viveiros, Jr. 

"Build An Amiga 20OO Keyboard For The Amiga 1000", Get a 

better- feeling keyboard for under $7.00, by Phillip R. Combs 

"Looking Beyond the Baud Rate", The Baud Bandit 2400 & 

Baud Bandit MNP/ Level 5 Plus modems, by B. P. Viveiros, Jr. 

"C Notes From The C Group", Programming with definitions 

known as "enumerated" data types, by Stephen Kemp 

"SAS/C Compiler", review by Bruce M. Drake 

"Mind ware's 3D Text Animator", review by Frank McMahon 

"A Little Closer lo Excellence", Micro-Systems Software's 

excellence! 2,0, review by Kim Schaffer 

¥ Vol. 5 No. 12, December 1990 

Highlights include: 

Twin Peaks Amiga Show Report", AC traveled to AmiEXPO 

in Anaheim,CA and World of Amiga inChicago, IL toreporton 

the newest and brightest Amiga products. 

"Information X-Change", Keepinguplodaleonthelatestnews 

via hardware, software, and cable TV, by Rick Broida 

"Stepper Motors", Part One of three pari series on building a 

simple stepper motor, by John Lovine 

"C Notes From The C Group", A discussion on cryptography, 

by Stephen Kemp 

"Pro Video Post", review by Frank McMahon 

"Feeding The Memory Monster", the 1CD AdRAM 540 and 

AdRAM 560D, review by Ernest P. Viveiros, Jr. 

"McGee & McGee Visits Katie's Farm", review by Jeff James 

"Wings", review by Rick Broida 

"MalhVision 2.0", review by R. Shamms Mortier 

" M.ik ing A Name For Yourself", Creating logos on the Amiga, 

by Frank McMahon 

"Hard Disk Primer For Floppy Users", Taking the sting outof 

the transition from floppies to hard drive, by Rob Hays 

"Shotgun Approach To Programming With AmigaBASIC, 

Bringing the fundamentals of Am igaBASlC programming into 

perspective, by Mike Morrison 



If Vol. 6 No. 1, January 1991 

Highlights include: 

"On The Road", coverage of Germany's Amiga '90, 

COMDEX in Nevada, and The World of Commodore Amiga 

in ToTonto, Canada 

"Electronic Color Splitter", an inexpensive way lo grab 

Images off video sources, by Greg Epley 

"Sketch Master", review by Ernest P. Viveiros, Jr. 

"Professional Draw 2.0", review by R. Shamms Mortier 

"Spell-A-Fari", review by Jeff James 

"Programming in AmigaBASIC, by Mike Morrison 

"ZoomBox", by John Leonard 

"Medley", AC's music column discusses MIDI, by Phil 

Saunders 

"Bug Bytes", a few problems with PageStream 2.0 and 

Quarterback Tools is raw shipping, by John Sleiner 

The Animation Studio", Disney's classic approach In a 

character animation program, by Frank McMahon 

"Forensic Animation", the Amiga helps out in the 

courtroom, by Andrew Lichtman 

"Cartoon Animation", back to the basics, by D* L- 

Richardson 

"Animation Chart", twenty-two animation packages and 

features 

"Memory & Animation", even 512K users can animate!, by 

Chris Boyce 

IfVoL 6 No. 2, February 1991 
Highlights Include: 

"Xeiec's CDx-650", CD-ROM technology for the Amiga, by 
Lonnie Watson 

"Distant Suns Libraries", Distant Suns expansion disks, by 
Jeff James 

"ANIMaglc", A graphics tool to spice up your presentations, 
by Rajesh Goel 

"Sharing Your Amiga Hard Drive With The Bridgeboard", 
Partition your hard drive to ruin both AmigaDOS and MS- 
DOS systems, by Gene Rawts 

"More Ports For Ydut Amiga", Building an I/O Expansion 
Board, by Jeff Lavin 

"Medley", A look at different types of music software 
available, by Phil Saunders 

"C Notes From The C Group", Creating a reminder 
program, by Stephen Kemp 
"Bug Bytes", New upgrades are in the works for 
PageStream and Professional Page, by John Steiner 
The 9-to~5 Amiga", by Daryell Sipper 
"Gold Disk Office", by Chuck Raudonis 
"dataT AX", by Daryell Sipper 
"Gold Disk's Desktop Budget", by Chuck Raudonis 
"BCraphics", by Chuck Raudonis 

If Vol. 6 No, 3, March 1991 

Highlights include: 

"Winter '91 CES", CDTV developers demonstrate upcoming 

releases and Amiga games developers present their latest 

creations in Las Vegas, Nevada 

"NewTek's Video Toaster A New Era In Amiga Video", a 

complete tour of the Video Toaster, by Frank McMahon 

"Ultrasonic Ranging System", the sonar system project 

continues with the assembly of an ultrasonic ranging 

system, by John lovine 

"Writing Faster Assembly Language", the discussion on 

how to speed; up programs with assembly is completed, by 

Martin F. Combs 

"Programming In AmigaBASIC Conditionals", using the 

IF/THEN statement in AmigaBasic, by Mike Morrison 

"New Products And Other Neat Stuff", an advanced ray- 

tradng module for 3-D Professional, Bars&Ptpes gets a price 

reduction, and DCTV is released, by John Rezendes 

"Bug Bytes", more workarounds for some popular 

programs, by John Steiner 

''Roomers", Is NewTek getting a run for their money with 

Digital Creations' V-Machine?, by The Bandito 

'Diversions", Nighl Shift, James Bond: The Stealth Affair, 

Wolf Pack, PowerMonger, and Harpoon are reviewed 

"Medley", leam how to load and modify MIDI files with 

your sequencer, by Phil Saunders 

"PD Serendipity", create your own menus to save to the 

bootblock with MenuWriler, or convert IFF pictures to C or 

assembly with IFF2Source, by Aimee B. Abren 

"C Notes From The C Group", working with functions in C, 

by Stephen Kemp 

"Spirit Technology's HDA-506", a less expensive 

alternative for Amiga 1000 £c 500 owners, by Mike C Corbett 

"Macro Paint", Lake Forest Logic's Dynamic hi-res, by R. 

Shamms Mortier 

"An Impulse To Imagine", review by R. Shamms Mortier 

'Top Form", Designing Minds' dedicated form publisher, by 

Jeff James 

"Quarterback Tools", a disk and file repair program lo help 

fix syslem crashes and accidental file deletions, by John 

Steiner 
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SAVE! SAVE! SAVE! 

If AC'S TECH is just what you've 
been looking for in an Amiga 
publication, don't just sit there - 

SUBSCRIBE! 

Also consider two more great 
reasons to be a subscriber - AC 
and AC'S GUIDE! Just fill out, clip 
and mail this card along with your 
payment to pick up on the 

SAVINGS! 



r 



YcS! The Amazing AC publications give me 3 GREAT reasons to save! 

Please begin the subscription(s) indicated below immediately! 

Name 



Address . 
City 



Slate 



ZIP 



ffl ^ 



Charge my EHVisa EHMC #_ 



Expiration Date . 



.Signature . 



VISA, 



Please circle lo indicale this Is a New Subscription or a Renewal 



1 year of AC'S TECH 


4 big issues of AC'S TECH! 
Limited Time Charter Offer! 


US$39.95 I ' J 
Canada/Mexico $43.95 □ 
Foreign Surface $47.95 I I 


1 year of AC 


12 big issues of Amazing Computing! 
Save over 49% off the cover price! 


US$24.00 I I 

Canada/Mexico $34.00 □ 
Foreign Surface $44.00 □ 


1-year SuperSub 


AC + AC'S GUIDE - 14 issues total! 
Save more than $31 off the cover prices! 


US $36.00 I I 

Canada/Mexico $54.00 □ 
Foreign Surface $64.00 □ 


2 years of AC 


24 big issues! Save over 59%! US only. 


US $38.00 [_| 


2-year SuperSub 


26 big issues! Save more than $75! US only. 


US $59.00 □ 



Check or money order payments must be In US funds drawn on a US bank; subject to applicable sales tax. 



Please return to: 



P.i.M. Publications, Inc. 

P.O. Box 869 

Fall River, MA 02722-0869 

Please place this order form in an envelope 
with your check or money order. 
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Captain's Log 217:2055 

Time shift equalization routines recodetl in 

Aztec C. Alt systems go. It's good to be back. home. 




Call Today for 
Product, Promotional 
and Pricing Information 



Aztec C is availablefof Amiga, Macintosh, MS-DOS, Apple H, 
TRS-80, and CPM/80. Native and cross development- 

Aztec Embedded C hosts on MS-DOS and Macintosh. Targets 
include: 68000 family, 8086 family, 8080/Z80/64180, & 6502 

Aztec C includes - C compiler, assembler, linker, librarian, 
editor, source debugger, and other development tools. 




nj%IXAJr800-221-0440 

• Outside USA: 908-542-2121 FAX: 908-542-8386 • Visa, MC, Am Ex, C.O.D, 
domestic & international wire • one and two day delivery available 



Manx Software Systems • 160 Avenue of the Commons • Box 55 • Shrewsbury NJ 07702 

Circle 187 on Reader Service card. 



Once you've made the commitment to scale the heights of personal computing 
with your Amiga, it's important to allocate your time and your money efficiently. 
You also want to come to play with as many quality tools as possible on a daily 

basis. MgSS5BBS-liinitrl l ;y l r.a 

j AC GUIDE^miga 

A one-year subscription to Amazing Computing fulfills these 
requirements completely and intelligently: AC is sent to your door 
monthly, and you pay just $2.00 per issue! And as an AC 
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products, technologies, and trends. You get fully detailed reviews, 
techniques, projects and analyses that help you develop and refine 
your skills on the Amiga every day. 

Include AC's GUIDE in your subscription for an informative and 

unsurpassed overview of the growing and ever-changing Amiga 

marketplace. At 320 pages. AG's GUIDE towers as the world's largest and 

most complete reference to everything presently available for the Amiga. And no I 

other Amiga publication gives you complete contact information for every 

known product developer and hundreds of users groups worldwide! 

And when you're ready to broaden the scope of your knowledge and ability to 
the maximum degree, expert technical proficiency is also within your grasp, 
thanks to AC's TECH. It's the first and best disk-based, all-technical, 
applications-intensive Amiga journal! 

Gather the skills and sharpen the tools you need to get the most from your Amiga 
as you accept the challenge of ascending to new heights! Subscribe to Amazing 
Computing, AC's GUIDE and AC'S TECH- today's incredible power trio of Amiga 
publications. 
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The smallest hard drive and interface in the world is now available 

for your Amiga 500 computer! This rugged little sweetheart mounts 

completely inside your computer allowing 20 megabytes of high 

speed storage that takes absoli-ely no desk space. The advanced 

features include autobooting from FastFileSystem partitions, high 

speed caching, auto-configuring, and A-Max II support. Novia 20i comes with complete instructions 

and all the hardware necessary for a simple, clean, no-solder installation. Available today at Amiga 

dealers everywhere. 

Novia is a trademark of ICD, Incorporated. Amiga is a registered trademark of Commodore-Amiga, Inc. A-Max II is a trademark of ReadySoft. 



ICD 



ICD. Incorporated 1 220 Rock Street Rockford, IL 61 101 

USA 

(815) 968-2228 Phone (815) 968-6888 FAX 

Circle 123 on Reader Service Card 



